System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 85ce79948116aa9a087ec345c9d2ce2c1d3cd8af:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  ** This file is 
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20  an amalgamation 
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65  of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20   C source files 
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76  from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 38 2e 38 2e 32 2e 20  ersion 3.8.8.2. 
00b0: 20 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c   By combining al
00c0: 6c 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c  l the individual
00d0: 20 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e   C code files in
00e0: 74 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67  to this .** sing
00f0: 6c 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74  le large file, t
0100: 68 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63  he entire code c
0110: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61  an be compiled a
0120: 73 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73  s a single trans
0130: 6c 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20  lation.** unit. 
0140: 20 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e   This allows man
0150: 79 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64  y compilers to d
0160: 6f 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  o optimizations 
0170: 74 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62  that would not b
0180: 65 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66  e.** possible if
0190: 20 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20   the files were 
01a0: 63 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74  compiled separat
01b0: 65 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63  ely.  Performanc
01c0: 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a  e improvements.*
01d0: 2a 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20  * of 5% or more 
01e0: 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65  are commonly see
01f0: 6e 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  n when SQLite is
0200: 20 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73   compiled as a s
0210: 69 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61  ingle.** transla
0220: 74 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a  tion unit..**.**
0230: 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c   This file is al
0240: 6c 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f  l you need to co
0250: 6d 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54  mpile SQLite.  T
0260: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20  o use SQLite in 
0270: 6f 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d  other.** program
0280: 73 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73  s, you need this
0290: 20 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73   file and the "s
02a0: 71 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72  qlite3.h" header
02b0: 20 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e   file that defin
02c0: 65 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61  es.** the progra
02d0: 6d 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  mming interface 
02e0: 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  to the SQLite li
02f0: 62 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20  brary.  (If you 
0300: 64 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20  do not have .** 
0310: 74 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20  the "sqlite3.h" 
0320: 68 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68  header file at h
0330: 61 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69  and, you will fi
0340: 6e 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64  nd a copy embedd
0350: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
0360: 20 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69   text of this fi
0370: 6c 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20  le.  Search for 
0380: 22 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69  "Begin file sqli
0390: 74 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74  te3.h" to find t
03a0: 68 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74  he start.** of t
03b0: 68 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69  he embedded sqli
03c0: 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c  te3.h header fil
03d0: 65 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63  e.) Additional c
03e0: 6f 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65  ode files may be
03f0: 20 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f   needed.** if yo
0400: 75 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72  u want a wrapper
0410: 20 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51   to interface SQ
0420: 4c 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63  Lite with your c
0430: 68 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d  hoice of program
0440: 6d 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65  ming.** language
0450: 2e 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74  . The code for t
0460: 68 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d  he "sqlite3" com
0470: 6d 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20  mand-line shell 
0480: 69 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20  is also in a.** 
0490: 73 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54  separate file. T
04a0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e  his file contain
04b0: 73 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20  s only code for 
04c0: 74 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20  the core SQLite 
04d0: 6c 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66  library..*/.#def
04e0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20  ine SQLITE_CORE 
04f0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
0500: 5f 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a  _AMALGAMATION 1.
0510: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50  #ifndef SQLITE_P
0520: 52 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20  RIVATE.# define 
0530: 53 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73  SQLITE_PRIVATE s
0540: 74 61 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66  tatic.#endif.#if
0550: 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a  ndef SQLITE_API.
0560: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
0570: 41 50 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a  API.#endif./****
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e  ********** Begin
0590: 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e   file sqliteInt.
05a0: 68 20 2a 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 2f 0a 2f 2a 0a 2a 2a  *********/./*.**
05d0: 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20   2001 September 
05e0: 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  15.**.** The aut
05f0: 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f  hor disclaims co
0600: 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20  pyright to this 
0610: 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e  source code.  In
0620: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c   place of.** a l
0630: 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72  egal notice, her
0640: 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a  e is a blessing:
0650: 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f  .**.**    May yo
0660: 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f  u do good and no
0670: 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61  t evil..**    Ma
0680: 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69  y you find forgi
0690: 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73  veness for yours
06a0: 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20  elf and forgive 
06b0: 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61  others..**    Ma
06c0: 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65  y you share free
06d0: 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67  ly, never taking
06e0: 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67   more than you g
06f0: 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a  ive..**.********
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 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e  *.** Internal in
0750: 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69  terface definiti
0760: 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a  ons for SQLite..
0770: 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53  **.*/.#ifndef _S
0780: 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66  QLITEINT_H_.#def
0790: 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48  ine _SQLITEINT_H
07a0: 5f 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65  _../*.** Include
07b0: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
07c0: 20 75 73 65 64 20 74 6f 20 63 75 73 74 6f 6d 69   used to customi
07d0: 7a 65 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 20  ze the compiler 
07e0: 6f 70 74 69 6f 6e 73 20 66 6f 72 20 4d 53 56 43  options for MSVC
07f0: 2e 0a 2a 2a 20 54 68 69 73 20 73 68 6f 75 6c 64  ..** This should
0800: 20 62 65 20 64 6f 6e 65 20 66 69 72 73 74 20 73   be done first s
0810: 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 75  o that it can su
0820: 63 63 65 73 73 66 75 6c 6c 79 20 70 72 65 76 65  ccessfully preve
0830: 6e 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a 20 63  nt spurious.** c
0840: 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73  ompiler warnings
0850: 20 64 75 65 20 74 6f 20 73 75 62 73 65 71 75 65   due to subseque
0860: 6e 74 20 63 6f 6e 74 65 6e 74 20 69 6e 20 74 68  nt content in th
0870: 69 73 20 66 69 6c 65 20 61 6e 64 20 6f 74 68 65  is file and othe
0880: 72 20 66 69 6c 65 73 0a 2a 2a 20 74 68 61 74 20  r files.** that 
0890: 61 72 65 20 69 6e 63 6c 75 64 65 64 20 62 79 20  are included by 
08a0: 74 68 69 73 20 66 69 6c 65 2e 0a 2a 2f 0a 2f 2a  this file..*/./*
08b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e  ************* In
08c0: 63 6c 75 64 65 20 6d 73 76 63 2e 68 20 69 6e 20  clude msvc.h in 
08d0: 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71  the middle of sq
08e0: 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a  liteInt.h ******
08f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a  ************/./*
0900: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65  ************* Be
0910: 67 69 6e 20 66 69 6c 65 20 6d 73 76 63 2e 68 20  gin file msvc.h 
0920: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0930: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0940: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a  ************/./*
0950: 0a 2a 2a 20 32 30 31 35 20 4a 61 6e 75 61 72 79  .** 2015 January
0960: 20 31 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75   12.**.** The au
0970: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
0980: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
0990: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
09a0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
09b0: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
09c0: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
09d0: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
09e0: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
09f0: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0a00: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0a10: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
0a20: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
0a30: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
0a40: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
0a50: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
0a60: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
0a70: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
0a80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0aa0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ab0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ac0: 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68  *******.**.** Th
0ad0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
0ae0: 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 73 70   code that is sp
0af0: 65 63 69 66 69 63 20 74 6f 20 4d 53 56 43 2e 0a  ecific to MSVC..
0b00: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 4d 53 56 43  */.#ifndef _MSVC
0b10: 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 4d 53 56  _H_.#define _MSV
0b20: 43 5f 48 5f 0a 0a 23 69 66 20 64 65 66 69 6e 65  C_H_..#if define
0b30: 64 28 5f 4d 53 43 5f 56 45 52 29 0a 23 70 72 61  d(_MSC_VER).#pra
0b40: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0b50: 62 6c 65 20 3a 20 34 30 35 34 29 0a 23 70 72 61  ble : 4054).#pra
0b60: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0b70: 62 6c 65 20 3a 20 34 30 35 35 29 0a 23 70 72 61  ble : 4055).#pra
0b80: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0b90: 62 6c 65 20 3a 20 34 31 30 30 29 0a 23 70 72 61  ble : 4100).#pra
0ba0: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0bb0: 62 6c 65 20 3a 20 34 31 32 37 29 0a 23 70 72 61  ble : 4127).#pra
0bc0: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0bd0: 62 6c 65 20 3a 20 34 31 35 32 29 0a 23 70 72 61  ble : 4152).#pra
0be0: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0bf0: 62 6c 65 20 3a 20 34 31 38 39 29 0a 23 70 72 61  ble : 4189).#pra
0c00: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0c10: 62 6c 65 20 3a 20 34 32 30 36 29 0a 23 70 72 61  ble : 4206).#pra
0c20: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0c30: 62 6c 65 20 3a 20 34 32 31 30 29 0a 23 70 72 61  ble : 4210).#pra
0c40: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0c50: 62 6c 65 20 3a 20 34 32 33 32 29 0a 23 70 72 61  ble : 4232).#pra
0c60: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0c70: 62 6c 65 20 3a 20 34 32 34 34 29 0a 23 70 72 61  ble : 4244).#pra
0c80: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0c90: 62 6c 65 20 3a 20 34 33 30 35 29 0a 23 70 72 61  ble : 4305).#pra
0ca0: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0cb0: 62 6c 65 20 3a 20 34 33 30 36 29 0a 23 70 72 61  ble : 4306).#pra
0cc0: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0cd0: 62 6c 65 20 3a 20 34 37 30 32 29 0a 23 70 72 61  ble : 4702).#pra
0ce0: 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73 61  gma warning(disa
0cf0: 62 6c 65 20 3a 20 34 37 30 36 29 0a 23 65 6e 64  ble : 4706).#end
0d00: 69 66 20 2f 2a 20 64 65 66 69 6e 65 64 28 5f 4d  if /* defined(_M
0d10: 53 43 5f 56 45 52 29 20 2a 2f 0a 0a 23 65 6e 64  SC_VER) */..#end
0d20: 69 66 20 2f 2a 20 5f 4d 53 56 43 5f 48 5f 20 2a  if /* _MSVC_H_ *
0d30: 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /../************
0d40: 2a 2a 20 45 6e 64 20 6f 66 20 6d 73 76 63 2e 68  ** End of msvc.h
0d50: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
0d60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d80: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
0d90: 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68  ** Continuing wh
0da0: 65 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20  ere we left off 
0db0: 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a  in sqliteInt.h *
0dc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0dd0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20  */../*.** These 
0de0: 23 64 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20  #defines should 
0df0: 65 6e 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65  enable >2GB file
0e00: 20 73 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49   support on POSI
0e10: 58 20 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  X if the.** unde
0e20: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
0e30: 20 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73   system supports
0e40: 20 69 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20   it.  If the OS 
0e50: 6c 61 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66  lacks.** large f
0e60: 69 6c 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20  ile support, or 
0e70: 69 66 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e  if the OS is win
0e80: 64 6f 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75  dows, these shou
0e90: 6c 64 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  ld be no-ops..**
0ea0: 0a 2a 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39  .** Ticket #2739
0eb0: 3a 20 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c  :  The _LARGEFIL
0ec0: 45 5f 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d  E_SOURCE macro m
0ed0: 75 73 74 20 61 70 70 65 61 72 20 62 65 66 6f 72  ust appear befor
0ee0: 65 20 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20  e any.** system 
0ef0: 23 69 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63  #includes.  Henc
0f00: 65 2c 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66  e, this block of
0f10: 20 63 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68   code must be th
0f20: 65 20 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20  e very first.** 
0f30: 63 6f 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72  code in all sour
0f40: 63 65 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  ce files..**.** 
0f50: 4c 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f  Large file suppo
0f60: 72 74 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c  rt can be disabl
0f70: 65 64 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53  ed using the -DS
0f80: 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46  QLITE_DISABLE_LF
0f90: 53 20 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74  S switch.** on t
0fa0: 68 65 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d  he compiler comm
0fb0: 61 6e 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20  and line.  This 
0fc0: 69 73 20 6e 65 63 65 73 73 61 72 79 20 69 66 20  is necessary if 
0fd0: 79 6f 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e  you are compilin
0fe0: 67 0a 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74  g.** on a recent
0ff0: 20 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65   machine (ex: Re
1000: 64 20 48 61 74 20 37 2e 32 29 20 62 75 74 20 79  d Hat 7.2) but y
1010: 6f 75 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64  ou want your cod
1020: 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20  e to work.** on 
1030: 61 6e 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65  an older machine
1040: 20 28 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e   (ex: Red Hat 6.
1050: 30 29 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70  0).  If you comp
1060: 69 6c 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37  ile on Red Hat 7
1070: 2e 32 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68  .2.** without th
1080: 69 73 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69  is option, LFS i
1090: 73 20 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c  s enable.  But L
10a0: 46 53 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73  FS does not exis
10b0: 74 20 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a  t in the kernel.
10c0: 2a 2a 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e  ** in Red Hat 6.
10d0: 30 2c 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77  0, so the code w
10e0: 6f 6e 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63  on't work.  Henc
10f0: 65 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62  e, for maximum b
1100: 69 6e 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69  inary.** portabi
1110: 6c 69 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20  lity you should 
1120: 6f 6d 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20  omit LFS..**.** 
1130: 54 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  The previous par
1140: 61 67 72 61 70 68 20 77 61 73 20 77 72 69 74 74  agraph was writt
1150: 65 6e 20 69 6e 20 32 30 30 35 2e 20 20 28 54 68  en in 2005.  (Th
1160: 69 73 20 70 61 72 61 67 72 61 70 68 20 69 73 20  is paragraph is 
1170: 77 72 69 74 74 65 6e 0a 2a 2a 20 6f 6e 20 32 30  written.** on 20
1180: 30 38 2d 31 31 2d 32 38 2e 29 20 54 68 65 73 65  08-11-28.) These
1190: 20 64 61 79 73 2c 20 61 6c 6c 20 4c 69 6e 75 78   days, all Linux
11a0: 20 6b 65 72 6e 65 6c 73 20 73 75 70 70 6f 72 74   kernels support
11b0: 20 6c 61 72 67 65 20 66 69 6c 65 73 2c 20 73 6f   large files, so
11c0: 0a 2a 2a 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  .** you should p
11d0: 72 6f 62 61 62 6c 79 20 6c 65 61 76 65 20 4c 46  robably leave LF
11e0: 53 20 65 6e 61 62 6c 65 64 2e 20 20 42 75 74 20  S enabled.  But 
11f0: 73 6f 6d 65 20 65 6d 62 65 64 64 65 64 20 70 6c  some embedded pl
1200: 61 74 66 6f 72 6d 73 20 6d 69 67 68 74 0a 2a 2a  atforms might.**
1210: 20 6c 61 63 6b 20 4c 46 53 20 69 6e 20 77 68 69   lack LFS in whi
1220: 63 68 20 63 61 73 65 20 74 68 65 20 53 51 4c 49  ch case the SQLI
1230: 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20 6d  TE_DISABLE_LFS m
1240: 61 63 72 6f 20 6d 69 67 68 74 20 73 74 69 6c 6c  acro might still
1250: 20 62 65 20 75 73 65 66 75 6c 2e 0a 2a 2a 0a 2a   be useful..**.*
1260: 2a 20 53 69 6d 69 6c 61 72 20 69 73 20 74 72 75  * Similar is tru
1270: 65 20 66 6f 72 20 4d 61 63 20 4f 53 20 58 2e 20  e for Mac OS X. 
1280: 20 4c 46 53 20 69 73 20 6f 6e 6c 79 20 73 75 70   LFS is only sup
1290: 70 6f 72 74 65 64 20 6f 6e 20 4d 61 63 20 4f 53  ported on Mac OS
12a0: 20 58 20 39 20 61 6e 64 20 6c 61 74 65 72 2e 0a   X 9 and later..
12b0: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
12c0: 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 0a 23 20  E_DISABLE_LFS.# 
12d0: 64 65 66 69 6e 65 20 5f 4c 41 52 47 45 5f 46 49  define _LARGE_FI
12e0: 4c 45 20 20 20 20 20 20 20 31 0a 23 20 69 66 6e  LE       1.# ifn
12f0: 64 65 66 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54  def _FILE_OFFSET
1300: 5f 42 49 54 53 0a 23 20 20 20 64 65 66 69 6e 65  _BITS.#   define
1310: 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49   _FILE_OFFSET_BI
1320: 54 53 20 36 34 0a 23 20 65 6e 64 69 66 0a 23 20  TS 64.# endif.# 
1330: 64 65 66 69 6e 65 20 5f 4c 41 52 47 45 46 49 4c  define _LARGEFIL
1340: 45 5f 53 4f 55 52 43 45 20 31 0a 23 65 6e 64 69  E_SOURCE 1.#endi
1350: 66 0a 0a 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72  f../* Needed for
1360: 20 76 61 72 69 6f 75 73 20 64 65 66 69 6e 69 74   various definit
1370: 69 6f 6e 73 2e 2e 2e 20 2a 2f 0a 23 69 66 20 64  ions... */.#if d
1380: 65 66 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f 29  efined(__GNUC__)
1390: 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 47 4e   && !defined(_GN
13a0: 55 5f 53 4f 55 52 43 45 29 0a 23 20 64 65 66 69  U_SOURCE).# defi
13b0: 6e 65 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23  ne _GNU_SOURCE.#
13c0: 65 6e 64 69 66 0a 0a 23 69 66 20 64 65 66 69 6e  endif..#if defin
13d0: 65 64 28 5f 5f 4f 70 65 6e 42 53 44 5f 5f 29 20  ed(__OpenBSD__) 
13e0: 26 26 20 21 64 65 66 69 6e 65 64 28 5f 42 53 44  && !defined(_BSD
13f0: 5f 53 4f 55 52 43 45 29 0a 23 20 64 65 66 69 6e  _SOURCE).# defin
1400: 65 20 5f 42 53 44 5f 53 4f 55 52 43 45 0a 23 65  e _BSD_SOURCE.#e
1410: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20  ndif../*.** For 
1420: 4d 69 6e 47 57 2c 20 63 68 65 63 6b 20 74 6f 20  MinGW, check to 
1430: 73 65 65 20 69 66 20 77 65 20 63 61 6e 20 69 6e  see if we can in
1440: 63 6c 75 64 65 20 74 68 65 20 68 65 61 64 65 72  clude the header
1450: 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 69 6e 67   file containing
1460: 20 69 74 73 0a 2a 2a 20 76 65 72 73 69 6f 6e 20   its.** version 
1470: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6d 6f  information, amo
1480: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2e  ng other things.
1490: 20 20 4e 6f 72 6d 61 6c 6c 79 2c 20 74 68 69 73    Normally, this
14a0: 20 69 6e 74 65 72 6e 61 6c 20 4d 69 6e 47 57 0a   internal MinGW.
14b0: 2a 2a 20 68 65 61 64 65 72 20 66 69 6c 65 20 77  ** header file w
14c0: 6f 75 6c 64 20 5b 6f 6e 6c 79 5d 20 62 65 20 69  ould [only] be i
14d0: 6e 63 6c 75 64 65 64 20 61 75 74 6f 6d 61 74 69  ncluded automati
14e0: 63 61 6c 6c 79 20 62 79 20 6f 74 68 65 72 20 4d  cally by other M
14f0: 69 6e 47 57 20 68 65 61 64 65 72 0a 2a 2a 20 66  inGW header.** f
1500: 69 6c 65 73 3b 20 68 6f 77 65 76 65 72 2c 20 74  iles; however, t
1510: 68 65 20 63 6f 6e 74 61 69 6e 65 64 20 76 65 72  he contained ver
1520: 73 69 6f 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sion information
1530: 20 69 73 20 6e 6f 77 20 72 65 71 75 69 72 65 64   is now required
1540: 20 62 79 20 74 68 69 73 0a 2a 2a 20 68 65 61 64   by this.** head
1550: 65 72 20 66 69 6c 65 20 74 6f 20 77 6f 72 6b 20  er file to work 
1560: 61 72 6f 75 6e 64 20 62 69 6e 61 72 79 20 63 6f  around binary co
1570: 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73 73 75  mpatibility issu
1580: 65 73 20 28 73 65 65 20 62 65 6c 6f 77 29 20 61  es (see below) a
1590: 6e 64 0a 2a 2a 20 74 68 69 73 20 69 73 20 74 68  nd.** this is th
15a0: 65 20 6f 6e 6c 79 20 6b 6e 6f 77 6e 20 77 61 79  e only known way
15b0: 20 74 6f 20 72 65 6c 69 61 62 6c 79 20 6f 62 74   to reliably obt
15c0: 61 69 6e 20 69 74 2e 20 20 54 68 69 73 20 65 6e  ain it.  This en
15d0: 74 69 72 65 20 23 69 66 20 62 6c 6f 63 6b 0a 2a  tire #if block.*
15e0: 2a 20 77 6f 75 6c 64 20 62 65 20 63 6f 6d 70 6c  * would be compl
15f0: 65 74 65 6c 79 20 75 6e 6e 65 63 65 73 73 61 72  etely unnecessar
1600: 79 20 69 66 20 74 68 65 72 65 20 77 61 73 20 61  y if there was a
1610: 6e 79 20 6f 74 68 65 72 20 77 61 79 20 6f 66 20  ny other way of 
1620: 64 65 74 65 63 74 69 6e 67 0a 2a 2a 20 4d 69 6e  detecting.** Min
1630: 47 57 20 76 69 61 20 74 68 65 69 72 20 70 72 65  GW via their pre
1640: 70 72 6f 63 65 73 73 6f 72 20 28 65 2e 67 2e 20  processor (e.g. 
1650: 69 66 20 74 68 65 79 20 63 75 73 74 6f 6d 69 7a  if they customiz
1660: 65 64 20 74 68 65 69 72 20 47 43 43 20 74 6f 20  ed their GCC to 
1670: 64 65 66 69 6e 65 0a 2a 2a 20 73 6f 6d 65 20 4d  define.** some M
1680: 69 6e 47 57 2d 73 70 65 63 69 66 69 63 20 6d 61  inGW-specific ma
1690: 63 72 6f 73 29 2e 20 20 57 68 65 6e 20 63 6f 6d  cros).  When com
16a0: 70 69 6c 69 6e 67 20 66 6f 72 20 4d 69 6e 47 57  piling for MinGW
16b0: 2c 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20  , either the.** 
16c0: 5f 48 41 56 45 5f 4d 49 4e 47 57 5f 48 20 6f 72  _HAVE_MINGW_H or
16d0: 20 5f 48 41 56 45 5f 5f 4d 49 4e 47 57 5f 48 20   _HAVE__MINGW_H 
16e0: 28 6e 6f 74 65 20 74 68 65 20 65 78 74 72 61 20  (note the extra 
16f0: 75 6e 64 65 72 73 63 6f 72 65 29 20 6d 61 63 72  underscore) macr
1700: 6f 20 6d 75 73 74 20 62 65 0a 2a 2a 20 64 65 66  o must be.** def
1710: 69 6e 65 64 3b 20 6f 74 68 65 72 77 69 73 65 2c  ined; otherwise,
1720: 20 64 65 74 65 63 74 69 6f 6e 20 6f 66 20 63 6f   detection of co
1730: 6e 64 69 74 69 6f 6e 73 20 73 70 65 63 69 66 69  nditions specifi
1740: 63 20 74 6f 20 4d 69 6e 47 57 20 77 69 6c 6c 20  c to MinGW will 
1750: 62 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  be.** disabled..
1760: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f  */.#if defined(_
1770: 48 41 56 45 5f 4d 49 4e 47 57 5f 48 29 0a 23 20  HAVE_MINGW_H).# 
1780: 69 6e 63 6c 75 64 65 20 22 6d 69 6e 67 77 2e 68  include "mingw.h
1790: 22 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ".#elif defined(
17a0: 5f 48 41 56 45 5f 5f 4d 49 4e 47 57 5f 48 29 0a  _HAVE__MINGW_H).
17b0: 23 20 69 6e 63 6c 75 64 65 20 22 5f 6d 69 6e 67  # include "_ming
17c0: 77 2e 68 22 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  w.h".#endif../*.
17d0: 2a 2a 20 46 6f 72 20 4d 69 6e 47 57 20 76 65 72  ** For MinGW ver
17e0: 73 69 6f 6e 20 34 2e 78 20 28 61 6e 64 20 68 69  sion 4.x (and hi
17f0: 67 68 65 72 29 2c 20 63 68 65 63 6b 20 74 6f 20  gher), check to 
1800: 73 65 65 20 69 66 20 74 68 65 20 5f 55 53 45 5f  see if the _USE_
1810: 33 32 42 49 54 5f 54 49 4d 45 5f 54 0a 2a 2a 20  32BIT_TIME_T.** 
1820: 64 65 66 69 6e 65 20 69 73 20 72 65 71 75 69 72  define is requir
1830: 65 64 20 74 6f 20 6d 61 69 6e 74 61 69 6e 20 62  ed to maintain b
1840: 69 6e 61 72 79 20 63 6f 6d 70 61 74 69 62 69 6c  inary compatibil
1850: 69 74 79 20 77 69 74 68 20 74 68 65 20 4d 53 56  ity with the MSV
1860: 43 20 72 75 6e 74 69 6d 65 0a 2a 2a 20 6c 69 62  C runtime.** lib
1870: 72 61 72 79 20 69 6e 20 75 73 65 20 28 65 2e 67  rary in use (e.g
1880: 2e 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 58 50  . for Windows XP
1890: 29 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e  )..*/.#if !defin
18a0: 65 64 28 5f 55 53 45 5f 33 32 42 49 54 5f 54 49  ed(_USE_32BIT_TI
18b0: 4d 45 5f 54 29 20 26 26 20 21 64 65 66 69 6e 65  ME_T) && !define
18c0: 64 28 5f 55 53 45 5f 36 34 42 49 54 5f 54 49 4d  d(_USE_64BIT_TIM
18d0: 45 5f 54 29 20 26 26 20 5c 0a 20 20 20 20 64 65  E_T) && \.    de
18e0: 66 69 6e 65 64 28 5f 57 49 4e 33 32 29 20 26 26  fined(_WIN32) &&
18f0: 20 21 64 65 66 69 6e 65 64 28 5f 57 49 4e 36 34   !defined(_WIN64
1900: 29 20 26 26 20 5c 0a 20 20 20 20 64 65 66 69 6e  ) && \.    defin
1910: 65 64 28 5f 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52  ed(__MINGW_MAJOR
1920: 5f 56 45 52 53 49 4f 4e 29 20 26 26 20 5f 5f 4d  _VERSION) && __M
1930: 49 4e 47 57 5f 4d 41 4a 4f 52 5f 56 45 52 53 49  INGW_MAJOR_VERSI
1940: 4f 4e 20 3e 3d 20 34 20 26 26 20 5c 0a 20 20 20  ON >= 4 && \.   
1950: 20 64 65 66 69 6e 65 64 28 5f 5f 4d 53 56 43 52   defined(__MSVCR
1960: 54 5f 5f 29 0a 23 20 64 65 66 69 6e 65 20 5f 55  T__).# define _U
1970: 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f 54 0a  SE_32BIT_TIME_T.
1980: 23 65 6e 64 69 66 0a 0a 2f 2a 20 54 68 65 20 70  #endif../* The p
1990: 75 62 6c 69 63 20 53 51 4c 69 74 65 20 69 6e 74  ublic SQLite int
19a0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 5f 46 49  erface.  The _FI
19b0: 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 6d  LE_OFFSET_BITS m
19c0: 61 63 72 6f 20 6d 75 73 74 20 61 70 70 65 61 72  acro must appear
19d0: 0a 2a 2a 20 66 69 72 73 74 20 69 6e 20 51 4e 58  .** first in QNX
19e0: 2e 20 20 41 6c 73 6f 2c 20 74 68 65 20 5f 55 53  .  Also, the _US
19f0: 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f 54 20 6d  E_32BIT_TIME_T m
1a00: 61 63 72 6f 20 6d 75 73 74 20 61 70 70 65 61 72  acro must appear
1a10: 20 66 69 72 73 74 20 66 6f 72 0a 2a 2a 20 4d 69   first for.** Mi
1a20: 6e 47 57 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  nGW..*/./*******
1a30: 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20  ******* Include 
1a40: 73 71 6c 69 74 65 33 2e 68 20 69 6e 20 74 68 65  sqlite3.h in the
1a50: 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74   middle of sqlit
1a60: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
1a70: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ******/./*******
1a80: 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69  ******* Begin fi
1a90: 6c 65 20 73 71 6c 69 74 65 33 2e 68 20 2a 2a 2a  le sqlite3.h ***
1aa0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ab0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ac0: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30  ******/./*.** 20
1ad0: 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 35 0a  01 September 15.
1ae0: 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
1af0: 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 72   disclaims copyr
1b00: 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f 75  ight to this sou
1b10: 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 6c  rce code.  In pl
1b20: 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 61  ace of.** a lega
1b30: 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 69  l notice, here i
1b40: 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a  s a blessing:.**
1b50: 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 64  .**    May you d
1b60: 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 65  o good and not e
1b70: 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79  vil..**    May y
1b80: 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65 6e  ou find forgiven
1b90: 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c 66  ess for yourself
1ba0: 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 68   and forgive oth
1bb0: 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79  ers..**    May y
1bc0: 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79 2c  ou share freely,
1bd0: 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d 6f   never taking mo
1be0: 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76 65  re than you give
1bf0: 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..**.***********
1c00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a  **************.*
1c40: 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66 69  * This header fi
1c50: 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  le defines the i
1c60: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74 68  nterface that th
1c70: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
1c80: 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f 20  .** presents to 
1c90: 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73 2e  client programs.
1ca0: 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69 6f    If a C-functio
1cb0: 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64 61  n, structure, da
1cc0: 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f  tatype,.** or co
1cd0: 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69 6f  nstant definitio
1ce0: 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  n does not appea
1cf0: 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c 20  r in this file, 
1d00: 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e 6f  then it is.** no
1d10: 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41 50  t a published AP
1d20: 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73 20  I of SQLite, is 
1d30: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
1d40: 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74  e without.** not
1d50: 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64 20  ice, and should 
1d60: 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63 65  not be reference
1d70: 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74 68  d by programs th
1d80: 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a 2a  at use SQLite..*
1d90: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
1da0: 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68 61   definitions tha
1db0: 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66 69  t are in this fi
1dc0: 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61 73  le are marked as
1dd0: 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74 61  .** "experimenta
1de0: 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74 61  l".  Experimenta
1df0: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
1e00: 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a   normally new.**
1e10: 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e 74   features recent
1e20: 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c 69  ly added to SQLi
1e30: 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 61  te.  We do not a
1e40: 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67 65  nticipate change
1e50: 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d 65  s.** to experime
1e60: 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  ntal interfaces 
1e70: 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65 20  but reserve the 
1e80: 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d 69  right to make mi
1e90: 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69  nor changes.** i
1ea0: 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f  f experience fro
1eb0: 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69  m use "in the wi
1ec0: 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68  ld" suggest such
1ed0: 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75   changes are pru
1ee0: 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dent..**.** The 
1ef0: 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75  official C-langu
1f00: 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74  age API document
1f10: 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65  ation for SQLite
1f20: 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66   is derived.** f
1f30: 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20  rom comments in 
1f40: 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73  this file.  This
1f50: 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74   file is the aut
1f60: 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63  horitative sourc
1f70: 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69  e.** on how SQLi
1f80: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
1f90: 65 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65  e suppose to ope
1fa0: 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rate..**.** The 
1fb0: 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c  name of this fil
1fc0: 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72  e under configur
1fd0: 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74  ation management
1fe0: 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e   is "sqlite.h.in
1ff0: 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69  "..** The makefi
2000: 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69  le makes some mi
2010: 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74  nor changes to t
2020: 68 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61  his file (such a
2030: 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74  s inserting.** t
2040: 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  he version numbe
2050: 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69  r) and changes i
2060: 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69  ts name to "sqli
2070: 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72  te3.h" as.** par
2080: 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70  t of the build p
2090: 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64  rocess..*/.#ifnd
20a0: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
20b0: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
20c0: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
20d0: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
20e0: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
20f0: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
2100: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
2110: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
2120: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
2130: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30  om C++..*/.#if 0
2140: 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65  .extern "C" {.#e
2150: 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64  ndif.../*.** Add
2160: 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   the ability to 
2170: 6f 76 65 72 72 69 64 65 20 27 65 78 74 65 72 6e  override 'extern
2180: 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  '.*/.#ifndef SQL
2190: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
21a0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
21b0: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
21c0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
21d0: 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  API.# define SQL
21e0: 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 0a  ITE_API.#endif..
21f0: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
2200: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
2210: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
2220: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
2230: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
2240: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
2250: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
2260: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
2270: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
2280: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
2290: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
22a0: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
22b0: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
22c0: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
22d0: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
22e0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
22f0: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
2300: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
2310: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
2320: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
2330: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
2340: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
2350: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
2360: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
2370: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
2380: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
2390: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
23a0: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
23b0: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
23c0: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
23d0: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
23e0: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
23f0: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
2400: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
2410: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
2420: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
2430: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
2440: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
2450: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
2460: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
2470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
2480: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
2490: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
24a0: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
24b0: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
24c0: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
24d0: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
24e0: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
24f0: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
2500: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
2510: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
2520: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
2530: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
2540: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
2550: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
2560: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
2570: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
2580: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
2590: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
25a0: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
25b0: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
25c0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
25d0: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
25e0: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
25f0: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
2600: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
2610: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
2620: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
2630: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
2640: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
2650: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
2660: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
2670: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
2680: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
2690: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
26a0: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
26b0: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
26c0: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
26d0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
26e0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
26f0: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
2700: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
2710: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
2720: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
2730: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
2740: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
2750: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
2760: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
2770: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
2780: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
2790: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
27a0: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
27b0: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
27c0: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
27d0: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
27e0: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
27f0: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
2800: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
2810: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
2820: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
2830: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
2840: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
2850: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
2860: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
2870: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
2880: 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38  e version 3.6.18
2890: 2c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  , SQLite source 
28a0: 63 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74  code has been st
28b0: 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c  ored in the.** <
28c0: 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77  a href="http://w
28d0: 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72  ww.fossil-scm.or
28e0: 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69  g/">Fossil confi
28f0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
2900: 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61  ent.** system</a
2910: 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  >.  ^The SQLITE_
2920: 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20  SOURCE_ID macro 
2930: 65 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20  evaluates to.** 
2940: 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
2950: 64 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74  dentifies a part
2960: 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20  icular check-in 
2970: 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74  of SQLite.** wit
2980: 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72  hin its configur
2990: 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74  ation management
29a0: 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53   system.  ^The S
29b0: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a  QLITE_SOURCE_ID.
29c0: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
29d0: 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20  ns the date and 
29e0: 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63  time of the chec
29f0: 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61  k-in (UTC) and a
2a00: 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f  n SHA1.** hash o
2a10: 66 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75  f the entire sou
2a20: 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20  rce tree..**.** 
2a30: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2a40: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d  e3_libversion()]
2a50: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69  ,.** [sqlite3_li
2a60: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
2a70: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75  )], [sqlite3_sou
2a80: 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  rceid()],.** [sq
2a90: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
2aa0: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
2ab0: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65  ce_id()]..*/.#de
2ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
2ad0: 49 4f 4e 20 20 20 20 20 20 20 20 22 33 2e 38 2e  ION        "3.8.
2ae0: 38 2e 32 22 0a 23 64 65 66 69 6e 65 20 53 51 4c  8.2".#define SQL
2af0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
2b00: 45 52 20 33 30 30 38 30 30 38 0a 23 64 65 66 69  ER 3008008.#defi
2b10: 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  ne SQLITE_SOURCE
2b20: 5f 49 44 20 20 20 20 20 20 22 32 30 31 35 2d 30  _ID      "2015-0
2b30: 31 2d 33 30 20 31 34 3a 33 30 3a 34 35 20 37 37  1-30 14:30:45 77
2b40: 35 37 66 63 37 32 31 32 32 30 65 31 33 36 36 32  57fc721220e13662
2b50: 30 61 38 39 63 39 64 32 38 32 34 37 66 32 38 62  0a89c9d28247f28b
2b60: 62 62 63 30 39 38 22 0a 0a 2f 2a 0a 2a 2a 20 43  bbc098"../*.** C
2b70: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
2b80: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
2b90: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
2ba0: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
2bb0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
2bc0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
2bd0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
2be0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
2bf0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
2c00: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
2c10: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
2c20: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
2c30: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
2c40: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
2c50: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
2c60: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
2c70: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
2c80: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
2c90: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
2ca0: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
2cb0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
2cc0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
2cd0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
2ce0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
2cf0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
2d00: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
2d10: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
2d20: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
2d30: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
2d40: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
2d50: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
2d60: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
2d70: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
2d80: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
2d90: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
2da0: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
2db0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
2dc0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
2dd0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
2de0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
2df0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
2e00: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
2e10: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
2e20: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
2e30: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
2e40: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
2e50: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
2e60: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
2e70: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
2e80: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
2e90: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
2ea0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
2eb0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
2ec0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
2ed0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
2ee0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
2ef0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2f00: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
2f10: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
2f20: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
2f30: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
2f40: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
2f50: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
2f60: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
2f70: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
2f80: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
2f90: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
2fa0: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
2fb0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
2fc0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
2fd0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
2fe0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
2ff0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
3000: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
3010: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
3020: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
3030: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
3040: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
3050: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
3060: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
3070: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
3080: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
3090: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
30a0: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
30b0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
30c0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
30d0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
30e0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
30f0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
3100: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
3110: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
3120: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
3130: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
3140: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69   const char sqli
3150: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d 20  te3_version[] = 
3160: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 3b 0a  SQLITE_VERSION;.
3170: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
3180: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c   char *sqlite3_l
3190: 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b  ibversion(void);
31a0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
31b0: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
31c0: 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a  sourceid(void);.
31d0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
31e0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
31f0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
3200: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3210: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
3220: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
3230: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
3240: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
3250: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
3260: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
3270: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
3280: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
3290: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
32a0: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
32b0: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
32c0: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
32d0: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
32e0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
32f0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
3300: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
3310: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
3320: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
3330: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
3340: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
3350: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
3360: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
3370: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
3380: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
3390: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
33a0: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
33b0: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
33c0: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
33d0: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
33e0: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
33f0: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
3400: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
3410: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
3420: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
3430: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
3440: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
3450: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
3460: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
3470: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
3480: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
3490: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
34a0: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
34b0: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
34c0: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
34d0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
34e0: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
34f0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
3500: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
3510: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
3520: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
3530: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
3540: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
3550: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
3560: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
3570: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
3580: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
3590: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
35a0: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
35b0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
35c0: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
35d0: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
35e0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
35f0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
3600: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
3610: 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  GS.SQLITE_API in
3620: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  t sqlite3_compil
3630: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e  eoption_used(con
3640: 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d  st char *zOptNam
3650: 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  e);.SQLITE_API c
3660: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
3670: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
3680: 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e  _get(int N);.#en
3690: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
36a0: 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65  REF: Test To See
36b0: 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20   If The Library 
36c0: 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a  Is Threadsafe.**
36d0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36e0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75  _threadsafe() fu
36f0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a  nction returns z
3700: 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ero if and only 
3710: 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73  if.** SQLite was
3720: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
3730: 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69  utexing code omi
3740: 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a  tted due to the.
3750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
3760: 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  DSAFE] compile-t
3770: 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67  ime option being
3780: 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a   set to 0..**.**
3790: 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63   SQLite can be c
37a0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20  ompiled with or 
37b0: 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e  without mutexes.
37c0: 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53    When.** the [S
37d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
37e0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
37f0: 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32   macro is 1 or 2
3800: 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  , mutexes.** are
3810: 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c   enabled and SQL
3820: 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ite is threadsaf
3830: 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20  e.  When the.** 
3840: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
3850: 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20  FE] macro is 0, 
3860: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20  .** the mutexes 
3870: 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69  are omitted.  Wi
3880: 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65  thout the mutexe
3890: 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66  s, it is not saf
38a0: 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69  e.** to use SQLi
38b0: 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20  te concurrently 
38c0: 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f  from more than o
38d0: 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a  ne thread..**.**
38e0: 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65   Enabling mutexe
38f0: 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75  s incurs a measu
3900: 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63  rable performanc
3910: 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f  e penalty..** So
3920: 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20   if speed is of 
3930: 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63  utmost importanc
3940: 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73  e, it makes sens
3950: 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20  e to disable.** 
3960: 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75  the mutexes.  Bu
3970: 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61  t for maximum sa
3980: 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68  fety, mutexes sh
3990: 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e  ould be enabled.
39a0: 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
39b0: 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72   behavior is for
39c0: 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65   mutexes to be e
39d0: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  nabled..**.** Th
39e0: 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
39f0: 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61   be used by an a
3a00: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61  pplication to ma
3a10: 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65  ke sure that the
3a20: 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53  .** version of S
3a30: 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73  QLite that it is
3a40: 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74   linking against
3a50: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
3a60: 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65  th.** the desire
3a70: 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65  d setting of the
3a80: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
3a90: 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  AFE] macro..**.*
3aa0: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
3ab0: 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e   only reports on
3ac0: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
3ad0: 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a  e mutex setting.
3ae0: 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ** of the [SQLIT
3af0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c  E_THREADSAFE] fl
3b00: 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ag.  If SQLite i
3b10: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
3b20: 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44  ** SQLITE_THREAD
3b30: 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65  SAFE=1 or =2 the
3b40: 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e  n mutexes are en
3b50: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
3b60: 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66   but.** can be f
3b70: 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c  ully or partiall
3b80: 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67  y disabled using
3b90: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
3ba0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a  te3_config()].**
3bb0: 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20   with the verbs 
3bc0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
3bd0: 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53  INGLETHREAD], [S
3be0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
3bf0: 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72  TITHREAD],.** or
3c00: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
3c10: 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28  SERIALIZED].  ^(
3c20: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
3c30: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
3c40: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
3c50: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
3c60: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
3c70: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
3c80: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
3c90: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
3ca0: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
3cb0: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
3cc0: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
3cd0: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
3ce0: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
3cf0: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
3d00: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
3d10: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
3d20: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
3d30: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
3d40: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
3d50: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
3d60: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
3d70: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
3d80: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53  nformation..*/.S
3d90: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
3da0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
3db0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
3dc0: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
3dd0: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
3de0: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  dle.** KEYWORDS:
3df0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
3e00: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
3e10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
3e20: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
3e30: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
3e40: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
3e50: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
3e60: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
3e70: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
3e80: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
3e90: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
3ea0: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
3eb0: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
3ec0: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
3ed0: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
3ee0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
3ef0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
3f00: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
3f10: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
3f20: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
3f30: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
3f40: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
3f50: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
3f60: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20  close_v2()] are 
3f70: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e  its destructors.
3f80: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
3f90: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
3fa0: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a  aces (such as.**
3fb0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3fc0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3fd0: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
3fe0: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
3ff0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
4000: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
4010: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
4020: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a  e methods on an.
4030: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63  ** sqlite3 objec
4040: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
4050: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
4060: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ite3;../*.** CAP
4070: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
4080: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b  teger Types.** K
4090: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
40a0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
40b0: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
40c0: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
40d0: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
40e0: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
40f0: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
4100: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
4110: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
4120: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
4130: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
4140: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
4150: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
4160: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
4170: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
4180: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
4190: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
41a0: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
41b0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
41c0: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
41d0: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
41e0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
41f0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
4200: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
4210: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79   sqlite_int64 ty
4220: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
4230: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  teger values.** 
4240: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32  between -9223372
4250: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64  036854775808 and
4260: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37   +92233720368547
4270: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e  75807 inclusive.
4280: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
4290: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  3_uint64 and sql
42a0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
42b0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
42c0: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65  er values .** be
42d0: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34  tween 0 and +184
42e0: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31  4674407370955161
42f0: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a  5 inclusive..*/.
4300: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
4310: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
4320: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
4330: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
4340: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
4350: 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54  igned SQLITE_INT
4360: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
4370: 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66  int64;.#elif def
4380: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c  ined(_MSC_VER) |
4390: 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c  | defined(__BORL
43a0: 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65  ANDC__).  typede
43b0: 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  f __int64 sqlite
43c0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
43d0: 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74  f unsigned __int
43e0: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
43f0: 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65  ;.#else.  typede
4400: 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  f long long int 
4410: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
4420: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
4430: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
4440: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
4450: 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c  ndif.typedef sql
4460: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
4470: 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66  3_int64;.typedef
4480: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73   sqlite_uint64 s
4490: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a  qlite3_uint64;..
44a0: 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69  /*.** If compili
44b0: 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73  ng for a process
44c0: 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c  or that lacks fl
44d0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70  oating point sup
44e0: 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74  port,.** substit
44f0: 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20  ute integer for 
4500: 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a  floating-point..
4510: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
4520: 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50  _OMIT_FLOATING_P
4530: 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f  OINT.# define do
4540: 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  uble sqlite3_int
4550: 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  64.#endif../*.**
4560: 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69   CAPI3REF: Closi
4570: 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  ng A Database Co
4580: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
4590: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  The sqlite3_clos
45a0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
45b0: 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69  close_v2() routi
45c0: 6e 65 73 20 61 72 65 20 64 65 73 74 72 75 63 74  nes are destruct
45d0: 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ors.** for the [
45e0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e  sqlite3] object.
45f0: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
4600: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
4610: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
4620: 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c  v2() return [SQL
4630: 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68  ITE_OK] if.** th
4640: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
4650: 63 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c  ct is successful
4660: 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64  ly destroyed and
4670: 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a   all associated.
4680: 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61 72 65  ** resources are
4690: 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a   deallocated..**
46a0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
46b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
46c0: 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
46d0: 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70  th unfinalized p
46e0: 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
46f0: 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73  ments or unfinis
4700: 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  hed sqlite3_back
4710: 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  up objects then 
4720: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a  sqlite3_close().
4730: 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68  ** will leave th
4740: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
4750: 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72  ction open and r
4760: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
4770: 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  SY]..** ^If sqli
4780: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
4790: 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e  s called with un
47a0: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
47b0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed statements.**
47c0: 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68   and/or unfinish
47d0: 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  ed sqlite3_backu
47e0: 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ps, then the dat
47f0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4800: 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75   becomes.** an u
4810: 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22  nusable "zombie"
4820: 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f   which will auto
4830: 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61  matically be dea
4840: 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68  llocated when th
4850: 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72  e.** last prepar
4860: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
4870: 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65  finalized or the
4880: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61   last sqlite3_ba
4890: 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73  ckup is.** finis
48a0: 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65  hed.  The sqlite
48b0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74  3_close_v2() int
48c0: 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64  erface is intend
48d0: 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a  ed for use with.
48e0: 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65  ** host language
48f0: 73 20 74 68 61 74 20 61 72 65 20 67 61 72 62 61  s that are garba
4900: 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e  ge collected, an
4910: 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 64 65  d where the orde
4920: 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65  r in which.** de
4930: 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 63 61  structors are ca
4940: 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 61 72  lled is arbitrar
4950: 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  y..**.** Applica
4960: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71  tions should [sq
4970: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
4980: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b   finalize] all [
4990: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
49a0: 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  nts],.** [sqlite
49b0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
49c0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
49d0: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a  handles], and .*
49e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
49f0: 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73  p_finish | finis
4a00: 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  h] all [sqlite3_
4a10: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
4a20: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
4a30: 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  th the [sqlite3]
4a40: 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f   object prior to
4a50: 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63   attempting to c
4a60: 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e  lose the object.
4a70: 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33    ^If.** sqlite3
4a80: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63  _close_v2() is c
4a90: 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61  alled on a [data
4aa0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
4ab0: 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a   that still has.
4ac0: 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b  ** outstanding [
4ad0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
4ae0: 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64  nts], [BLOB hand
4af0: 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  les], and/or.** 
4b00: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
4b10: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74   objects then it
4b20: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
4b30: 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61  _OK] and the dea
4b40: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
4b50: 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 66  resources is def
4b60: 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20  erred until all 
4b70: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
4b80: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e  ents], [BLOB han
4b90: 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73  dles],.** and [s
4ba0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
4bb0: 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20  bjects are also 
4bc0: 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a  destroyed..**.**
4bd0: 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33   ^If an [sqlite3
4be0: 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74  ] object is dest
4bf0: 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 72  royed while a tr
4c00: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65  ansaction is ope
4c10: 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61  n,.** the transa
4c20: 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74  ction is automat
4c30: 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
4c40: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20  ck..**.** The C 
4c50: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
4c60: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
4c70: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
4c80: 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73  se_v2(C)].** mus
4c90: 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
4ca0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72  LL.** pointer or
4cb0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
4cc0: 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74  ject pointer obt
4cd0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4ce0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
4cf0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
4d00: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
4d10: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
4d20: 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  nd not previousl
4d30: 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61  y closed..** ^Ca
4d40: 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c  lling sqlite3_cl
4d50: 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ose() or sqlite3
4d60: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68  _close_v2() with
4d70: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
4d80: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  ** argument is a
4d90: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
4da0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
4db0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
4dc0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
4dd0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
4de0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69  e3_close_v2(sqli
4df0: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  te3*);../*.** Th
4e00: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
4e10: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
4e20: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
4e30: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
4e40: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
4e50: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
4e60: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
4e70: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
4e80: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
4e90: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
4ea0: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
4eb0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
4ec0: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
4ed0: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
4ee0: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
4ef0: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a   Interface.**.**
4f00: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
4f10: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
4f20: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
4f30: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
4f40: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
4f50: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
4f60: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
4f70: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
4f80: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
4f90: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
4fa0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
4fb0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
4fc0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
4fd0: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
4fe0: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
4ff0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
5000: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
5010: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
5020: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
5030: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
5040: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
5050: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
5060: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
5070: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
5080: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
5090: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
50a0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
50b0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
50c0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
50d0: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
50e0: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
50f0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
5100: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
5110: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
5120: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
5130: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
5140: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
5150: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
5160: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
5170: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
5180: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
5190: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
51a0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
51b0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
51c0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
51d0: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
51e0: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
51f0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
5200: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
5210: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
5220: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
5230: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
5240: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
5250: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
5260: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
5270: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
5280: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
5290: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
52a0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
52b0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
52c0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
52d0: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
52e0: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
52f0: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
5300: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
5310: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
5320: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
5330: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
5340: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
5350: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
5360: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
5370: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
5380: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
5390: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
53a0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
53b0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
53c0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
53d0: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
53e0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
53f0: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
5400: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
5410: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
5420: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
5430: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
5440: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
5450: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
5460: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
5470: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
5480: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
5490: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
54a0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
54b0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
54c0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
54d0: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
54e0: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
54f0: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
5500: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
5510: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
5520: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
5530: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
5540: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
5550: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
5560: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
5570: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
5580: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
5590: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
55a0: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
55b0: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
55c0: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
55d0: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
55e0: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
55f0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
5600: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
5610: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
5620: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
5630: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
5640: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
5650: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
5660: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
5670: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
5680: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
5690: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
56a0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
56b0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
56c0: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
56d0: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
56e0: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
56f0: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
5700: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
5710: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
5720: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
5730: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
5740: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
5750: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
5760: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
5770: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
5780: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
5790: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
57a0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
57b0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
57c0: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
57d0: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
57e0: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
57f0: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
5800: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
5810: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
5820: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
5830: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
5840: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
5850: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
5860: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
5870: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
5880: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
5890: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
58a0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
58b0: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
58c0: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
58d0: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
58e0: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
58f0: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
5900: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
5910: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
5920: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
5930: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
5940: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
5950: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
5960: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
5970: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
5980: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
5990: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
59a0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
59b0: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
59c0: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
59d0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
59e0: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
59f0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
5a00: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
5a10: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
5a20: 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
5a30: 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74  ied by.**      t
5a40: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
5a50: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
5a60: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
5a70: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
5a80: 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ng..** <li> The 
5a90: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
5aa0: 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20   not modify the 
5ab0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
5ac0: 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a  xt passed into.*
5ad0: 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 70  *      the 2nd p
5ae0: 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
5af0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
5b00: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
5b10: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
5b20: 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  /ul>.*/.SQLITE_A
5b30: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  PI int sqlite3_e
5b40: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  sqlite3*,
5b50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5b60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5b70: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
5b80: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
5b90: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
5ba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5bb0: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
5bc0: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
5bd0: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
5be0: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
5bf0: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
5c00: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
5c10: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  void *,  
5c20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5c30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5c40: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
5c50: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
5c60: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
5c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5c80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
5c90: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
5ca0: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
5cb0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
5cc0: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
5cd0: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
5ce0: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
5cf0: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
5d00: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
5d10: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
5d20: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
5d30: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
5d40: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
5d50: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63   to indicate suc
5d60: 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e  cess or failure.
5d70: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72  .**.** New error
5d80: 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64   codes may be ad
5d90: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65  ded in future ve
5da0: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
5db0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
5dc0: 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : [extended resu
5dd0: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
5de0: 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ons].*/.#define 
5df0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
5e00: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
5e10: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
5e20: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
5e30: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
5e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
5e50: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
5e60: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
5e70: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
5e80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e90: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
5ea0: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
5eb0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
5ec0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
5ed0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
5ee0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
5ef0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
5f00: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
5f10: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
5f20: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
5f30: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
5f40: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
5f50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f60: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
5f70: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
5f80: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
5f90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5fa0: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
5fb0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
5fc0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
5fd0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
5fe0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
5ff0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
6000: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
6010: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6020: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
6030: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
6040: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
6050: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
6060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
6070: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
6080: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
6090: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
60a0: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
60b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
60c0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
60d0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
60e0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
60f0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
6100: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
6110: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
6120: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
6130: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
6140: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
6150: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
6160: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
6170: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
6180: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
6190: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
61a0: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
61b0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
61c0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
61d0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
61e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
61f0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
6200: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
6210: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
6220: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
6230: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
6240: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
6250: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
6260: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
6270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
6280: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
6290: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
62a0: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
62b0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
62c0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
62d0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
62e0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
62f0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
6300: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
6310: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
6320: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
6330: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
6340: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
6350: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
6360: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
6370: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
6380: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
6390: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
63a0: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
63b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
63c0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
63d0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
63e0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
63f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
6400: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
6410: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
6420: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
6430: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
6440: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
6450: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
6460: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
6470: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
6480: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
6490: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
64a0: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
64b0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
64c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
64d0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
64e0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
64f0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
6500: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
6510: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
6520: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
6530: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
6540: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
6550: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
6560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6570: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
6580: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
6590: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
65a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
65b0: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
65c0: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
65d0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
65e0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
65f0: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
6600: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
6610: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
6620: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
6630: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6640: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
6650: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
6660: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
6670: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
6680: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
6690: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
66a0: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
66b0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
66c0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
66d0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
66e0: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
66f0: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
6700: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
6710: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
6720: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
6730: 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a  of 30 integer.**
6740: 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e   [result codes].
6750: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
6760: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
6770: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20  that many of.** 
6780: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
6790: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73  es are too coars
67a0: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
67b0: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
67c0: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
67d0: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
67e0: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
67f0: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
6800: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
6810: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
6820: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
6830: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
6840: 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c  sion 3.3.8 and l
6850: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a  ater) include.**
6860: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64   support for add
6870: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63  itional result c
6880: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64  odes that provid
6890: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
68a0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
68b0: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65  bout errors. The
68c0: 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  se [extended res
68d0: 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65  ult codes] are e
68e0: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
68f0: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64  ed.** on a per d
6900: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
6910: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74  on basis using t
6920: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
6930: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
6940: 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72  odes()] API.  Or
6950: 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63  , the extended c
6960: 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d  ode for.** the m
6970: 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72  ost recent error
6980: 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
6990: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
69a0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
69b0: 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  ode()]..*/.#defi
69c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
69d0: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
69e0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
69f0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
6a00: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
6a10: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
6a20: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
6a30: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
6a40: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
6a50: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
6a60: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
6a70: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
6a80: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
6a90: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
6aa0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
6ab0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
6ac0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
6ad0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
6ae0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
6af0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6b00: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
6b10: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
6b20: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
6b30: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
6b40: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
6b50: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
6b60: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
6b70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
6b80: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
6b90: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
6ba0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
6bb0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
6bc0: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
6bd0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
6be0: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
6bf0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6c00: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
6c10: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6c20: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
6c30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6c40: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
6c50: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6c60: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
6c70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6c80: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
6c90: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6ca0: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
6cb0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6cc0: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
6cd0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6ce0: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
6cf0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6d00: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
6d10: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
6d20: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
6d30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6d40: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
6d50: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6d60: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
6d70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6d80: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
6d90: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6da0: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
6db0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6dc0: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
6dd0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6de0: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
6df0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6e00: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20  _IOERR_SHMOPEN  
6e10: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6e20: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29  _IOERR | (18<<8)
6e30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6e40: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20  _IOERR_SHMSIZE  
6e50: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6e60: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29  _IOERR | (19<<8)
6e70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6e80: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20  _IOERR_SHMLOCK  
6e90: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6ea0: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29  _IOERR | (20<<8)
6eb0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6ec0: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20  _IOERR_SHMMAP   
6ed0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6ee0: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29  _IOERR | (21<<8)
6ef0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6f00: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20  _IOERR_SEEK     
6f10: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6f20: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29  _IOERR | (22<<8)
6f30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6f40: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f  _IOERR_DELETE_NO
6f50: 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45  ENT      (SQLITE
6f60: 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29  _IOERR | (23<<8)
6f70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6f80: 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20  _IOERR_MMAP     
6f90: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
6fa0: 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29  _IOERR | (24<<8)
6fb0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6fc0: 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41  _IOERR_GETTEMPPA
6fd0: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
6fe0: 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29  _IOERR | (25<<8)
6ff0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7000: 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20  _IOERR_CONVPATH 
7010: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7020: 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29  _IOERR | (26<<8)
7030: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7040: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
7050: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
7060: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
7070: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7080: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
7090: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
70a0: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
70b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
70c0: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54  TE_BUSY_SNAPSHOT
70d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
70e0: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c  TE_BUSY   |  (2<
70f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7100: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54  ITE_CANTOPEN_NOT
7110: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c  EMPDIR      (SQL
7120: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
7130: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
7140: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49  QLITE_CANTOPEN_I
7150: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53  SDIR          (S
7160: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
7170: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
7180: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
7190: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20  _FULLPATH       
71a0: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
71b0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
71c0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
71d0: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  EN_CONVPATH     
71e0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
71f0: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  EN | (4<<8)).#de
7200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
7210: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
7220: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
7230: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
7240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
7250: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
7260: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
7270: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
7280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
7290: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
72a0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
72b0: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
72c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
72d0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41  _READONLY_ROLLBA
72e0: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
72f0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c  _READONLY | (3<<
7300: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
7310: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f  TE_READONLY_DBMO
7320: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  VED        (SQLI
7330: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34  TE_READONLY | (4
7340: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7350: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
7360: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
7370: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
7380: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
73a0: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
73b0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
73c0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
73d0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
73e0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
73f0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
7400: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
7410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
7420: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
7430: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
7440: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
7450: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7460: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
7470: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
7480: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
7490: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
74a0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
74b0: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
74c0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
74d0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
74e0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
74f0: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
7500: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
7510: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
7520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
7530: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
7540: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
7550: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
7560: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7570: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
7580: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
7590: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
75a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
75b0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
75c0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
75d0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
75e0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
75f0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
7600: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
7610: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
7620: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
7630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
7640: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
7650: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
7660: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
7670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
7680: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
7690: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
76a0: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
76b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
76c0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
76d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
76e0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
76f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
7700: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
7710: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
7720: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  H | (1<<8))../*.
7730: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
7740: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
7750: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
7760: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
7770: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
7780: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
7790: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
77a0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
77b0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
77c0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
77d0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
77e0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
77f0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7800: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
7810: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
7820: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
7830: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
7840: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
7850: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
7860: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
7870: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
7880: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
7890: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
78a0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
78b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
78c0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
78d0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
78e0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
78f0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
7900: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
7910: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
7920: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
7930: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
7940: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
7950: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
7960: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
7970: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
7980: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
7990: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
79a0: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
79b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
79c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
79d0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
79e0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
79f0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
7a00: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
7a10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
7a20: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
7a30: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
7a40: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
7a50: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
7a60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
7a70: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
7a80: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
7a90: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
7aa0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
7ab0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
7ac0: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
7ad0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
7ae0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
7af0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
7b00: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
7b10: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
7b20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
7b30: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
7b40: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
7b50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
7b60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
7b70: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
7b80: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
7b90: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
7ba0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
7bb0: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
7bc0: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
7bd0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
7be0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
7bf0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
7c00: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
7c10: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
7c20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
7c30: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
7c40: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
7c50: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
7c60: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
7c70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
7c80: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
7c90: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
7ca0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
7cb0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
7cc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
7cd0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
7ce0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
7cf0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
7d00: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
7d10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
7d20: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
7d30: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
7d40: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
7d50: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
7d60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
7d70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7d80: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
7d90: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
7da0: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
7db0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
7dc0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
7dd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
7de0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
7df0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
7e00: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
7e10: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
7e20: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
7e30: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
7e40: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
7e50: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
7e60: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
7e70: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
7e80: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
7e90: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
7ea0: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
7eb0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
7ec0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
7ed0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
7ee0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
7ef0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
7f00: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7f10: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
7f20: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
7f30: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
7f40: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
7f50: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
7f60: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
7f70: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
7f80: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
7f90: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
7fa0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
7fb0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
7fc0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
7fd0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
7fe0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
7ff0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
8000: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8010: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
8020: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
8030: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
8040: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8050: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8060: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8070: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8080: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8090: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
80a0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
80b0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
80c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
80d0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
80e0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
80f0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
8100: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
8110: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
8120: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
8130: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
8140: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
8150: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
8160: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8170: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
8180: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
8190: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
81a0: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
81b0: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
81c0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
81d0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
81e0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
81f0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
8200: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
8210: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
8220: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
8230: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
8240: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
8250: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
8260: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
8270: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
8280: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
8290: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
82a0: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
82b0: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
82c0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
82d0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
82e0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
82f0: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
8300: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
8310: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
8320: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
8330: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
8340: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
8350: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
8360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
8370: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
8380: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
8390: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
83a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
83b0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
83c0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
83d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
83e0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
83f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
8400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8410: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
8420: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
8430: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
8440: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8450: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
8460: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
8470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
8480: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
8490: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
84a0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
84b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
84c0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
84d0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
84e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
84f0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
8500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8510: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
8520: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
8530: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
8540: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
8550: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
8560: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
8570: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
8580: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
8590: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
85a0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
85b0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
85c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
85d0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
85e0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
85f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8600: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
8610: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
8620: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
8630: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
8640: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
8650: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
8660: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
8670: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
8680: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
8690: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
86a0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
86b0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
86c0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
86d0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
86e0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
86f0: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
8700: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
8710: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8720: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
8730: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
8740: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
8750: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
8760: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
8770: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
8780: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
8790: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
87a0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
87b0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
87c0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
87d0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
87e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
87f0: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
8800: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
8810: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
8820: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
8830: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
8840: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
8850: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
8860: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
8870: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
8880: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
8890: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
88a0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
88b0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
88c0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
88d0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
88e0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
88f0: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
8900: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
8910: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
8920: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
8930: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
8940: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
8950: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
8960: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
8970: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
8980: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
8990: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
89a0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
89b0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
89c0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
89d0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
89e0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
89f0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
8a00: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
8a10: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
8a20: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
8a30: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
8a40: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
8a50: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
8a60: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
8a70: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
8a80: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
8a90: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
8aa0: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
8ab0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
8ac0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
8ad0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
8ae0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
8af0: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
8b00: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
8b10: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
8b20: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
8b30: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
8b40: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
8b50: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
8b60: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
8b70: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
8b80: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
8b90: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
8ba0: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
8bb0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
8bc0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
8bd0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
8be0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
8bf0: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
8c00: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
8c10: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
8c20: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8c30: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
8c40: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
8c50: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
8c60: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
8c70: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
8c80: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
8c90: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
8ca0: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
8cb0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
8cc0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
8cd0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
8ce0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
8cf0: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
8d00: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
8d10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
8d20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
8d30: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
8d40: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
8d50: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
8d60: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
8d70: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
8d80: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
8d90: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
8da0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
8db0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
8dc0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
8dd0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
8de0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
8df0: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
8e00: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
8e10: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
8e20: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
8e30: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
8e40: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
8e50: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
8e60: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
8e70: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
8e80: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
8e90: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
8ea0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
8eb0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
8ec0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
8ed0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
8ee0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
8ef0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
8f00: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
8f10: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
8f20: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
8f30: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
8f40: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
8f50: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
8f60: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
8f70: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8f80: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
8f90: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
8fa0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
8fb0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
8fc0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
8fd0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
8fe0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
8ff0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
9000: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
9010: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
9020: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
9030: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9040: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
9050: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
9060: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
9070: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9080: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
9090: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
90a0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
90b0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
90c0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
90d0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
90e0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
90f0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
9100: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
9110: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
9120: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
9130: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
9140: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
9150: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
9160: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
9170: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
9180: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
9190: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
91a0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
91b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
91c0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
91d0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
91e0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
91f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
9200: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
9210: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
9220: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
9230: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
9240: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
9250: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
9260: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
9270: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
9280: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
9290: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
92a0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
92b0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
92c0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
92d0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
92e0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
92f0: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
9300: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
9310: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
9320: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
9330: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
9340: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
9350: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
9360: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
9370: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
9380: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
9390: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
93a0: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
93b0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
93c0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
93d0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
93e0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
93f0: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
9400: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
9410: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
9420: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
9430: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
9440: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
9450: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
9460: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
9470: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
9480: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
9490: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
94a0: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
94b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
94c0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
94d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
94e0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
94f0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
9500: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
9510: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
9520: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
9530: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
9540: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
9550: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
9560: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
9570: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
9580: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
9590: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
95a0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
95b0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
95c0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
95d0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
95e0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
95f0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
9600: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
9610: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
9620: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
9630: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
9640: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
9650: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
9660: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
9670: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
9680: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
9690: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
96a0: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
96b0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
96c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
96d0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
96e0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
96f0: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
9700: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
9710: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
9720: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
9730: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
9740: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
9750: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
9760: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
9770: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
9780: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
9790: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
97a0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
97b0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
97c0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
97d0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
97e0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
97f0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
9800: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
9810: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
9820: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
9830: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
9840: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
9850: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
9860: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
9870: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
9880: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
9890: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
98a0: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
98b0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
98c0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
98d0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
98e0: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
98f0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
9900: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
9910: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
9920: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
9930: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
9940: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
9950: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
9960: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
9970: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
9980: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
9990: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
99a0: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
99b0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
99c0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
99d0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
99e0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
99f0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
9a00: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
9a10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
9a20: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
9a30: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
9a40: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
9a50: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
9a60: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
9a70: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
9a80: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
9a90: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
9aa0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
9ab0: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
9ac0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
9ad0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
9ae0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
9af0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
9b00: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
9b10: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
9b20: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
9b30: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
9b40: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
9b50: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
9b60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
9b70: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
9b80: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
9b90: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
9ba0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
9bb0: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
9bc0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
9bd0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
9be0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
9bf0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
9c00: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
9c10: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
9c20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
9c30: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
9c40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
9c50: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
9c60: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
9c70: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
9c80: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
9c90: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
9ca0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
9cb0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
9cc0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
9cd0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
9ce0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
9cf0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
9d00: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
9d10: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
9d20: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
9d30: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
9d40: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
9d50: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
9d60: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
9d70: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
9d80: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
9d90: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
9da0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
9db0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
9dc0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
9dd0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
9de0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
9df0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
9e00: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
9e10: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
9e20: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
9e30: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
9e40: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
9e50: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
9e60: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
9e70: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
9e80: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
9e90: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
9ea0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
9eb0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
9ec0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
9ed0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
9ee0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
9ef0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
9f00: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
9f10: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
9f20: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
9f30: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
9f40: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
9f50: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
9f60: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
9f70: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
9f80: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
9f90: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
9fa0: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
9fb0: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
9fc0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
9fd0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
9fe0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
9ff0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
a000: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
a010: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
a020: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
a030: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
a040: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
a050: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
a060: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
a070: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
a080: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
a090: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
a0a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
a0b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a0c0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
a0d0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
a0e0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
a0f0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
a100: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
a110: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
a120: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
a130: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
a140: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
a150: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
a160: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
a170: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
a180: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
a190: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
a1a0: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
a1b0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
a1c0: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
a1d0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
a1e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
a1f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
a200: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
a210: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
a220: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
a230: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
a240: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
a250: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
a260: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
a270: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
a280: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
a290: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
a2a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
a2b0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
a2c0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
a2d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
a2e0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
a2f0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
a300: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
a310: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
a320: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
a330: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
a340: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
a350: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
a360: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
a370: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
a380: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
a390: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
a3a0: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
a3b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
a3c0: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
a3d0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a3e0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
a3f0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
a400: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
a410: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
a420: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
a430: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
a440: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
a450: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
a460: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
a470: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
a480: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
a490: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
a4a0: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
a4b0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
a4c0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
a4d0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
a4e0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
a4f0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
a500: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
a510: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
a520: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
a530: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
a540: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
a550: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
a560: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
a570: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
a580: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
a590: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
a5a0: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
a5b0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
a5c0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
a5d0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
a5e0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
a5f0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
a600: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
a610: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
a620: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
a630: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
a640: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
a650: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
a660: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
a670: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
a680: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
a690: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
a6a0: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
a6b0: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
a6c0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
a6d0: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
a6e0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
a6f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
a700: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
a710: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
a720: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
a730: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
a740: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
a750: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
a760: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
a770: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
a780: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
a790: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
a7a0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
a7b0: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
a7c0: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
a7d0: 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ined..** <ul>.**
a7e0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a7f0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a  NTL_SIZE_HINT]].
a800: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
a810: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20  CNTL_SIZE_HINT] 
a820: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62  opcode is used b
a830: 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65  y SQLite to give
a840: 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65   the VFS.** laye
a850: 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20  r a hint of how 
a860: 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61  large the databa
a870: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f  se file will gro
a880: 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74  w to be during t
a890: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72  he.** current tr
a8a0: 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73  ansaction.  This
a8b0: 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61   hint is not gua
a8c0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63  ranteed to be ac
a8d0: 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a  curate but it.**
a8e0: 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e   is often close.
a8f0: 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67    The underlying
a900: 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73   VFS might choos
a910: 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65  e to preallocate
a920: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
a930: 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e  e space based on
a940: 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72   this hint in or
a950: 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74  der to help writ
a960: 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  es to the databa
a970: 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66  se.** file run f
a980: 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  aster..**.** <li
a990: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a9a0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  CHUNK_SIZE]].** 
a9b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a9c0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
a9d0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
a9e0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
a9f0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
aa00: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
aa10: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
aa20: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
aa30: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
aa40: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
aa50: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
aa60: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
aa70: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
aa80: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
aa90: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
aaa0: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
aab0: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
aac0: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
aad0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
aae0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
aaf0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
ab00: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
ab10: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
ab20: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
ab30: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
ab40: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
ab50: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
ab60: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
ab70: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
ab80: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ms..**.** <li>[[
ab90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
aba0: 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  E_POINTER]].** T
abb0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
abc0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f  _FILE_POINTER] o
abd0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
abe0: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
abf0: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
ac00: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
ac10: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
ac20: 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
ac30: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
ac40: 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20  ction.  See the 
ac50: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
ac60: 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e  ntrol()] documen
ac70: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64  tation for.** ad
ac80: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
ac90: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
aca0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
acb0: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a  YNC_OMITTED]].**
acc0: 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73   No longer in us
acd0: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
ace0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
acf0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
ad00: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70  E_FCNTL_SYNC] op
ad10: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
ad20: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
ad30: 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65  SQLite and.** se
ad40: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d  nt to the VFS im
ad50: 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65  mediately before
ad60: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
ad70: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  d is invoked on 
ad80: 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69  a.** database fi
ad90: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f  le descriptor. O
ada0: 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20  r, if the xSync 
adb0: 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e  method is not in
adc0: 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73  voked .** becaus
add0: 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63  e the user has c
ade0: 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65  onfigured SQLite
adf0: 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d   with .** [PRAGM
ae00: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
ae10: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
ae20: 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e  us=OFF] it is in
ae30: 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a  voked in place .
ae40: 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20  ** of the xSync 
ae50: 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20  method. In most 
ae60: 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74  cases, the point
ae70: 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  er argument pass
ae80: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20  ed with.** this 
ae90: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
aea0: 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69  NULL. However, i
aeb0: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
aec0: 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e  ile is being syn
aed0: 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  ced.** as part o
aee0: 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61  f a multi-databa
aef0: 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61  se commit, the a
af00: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
af10: 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  o a nul-terminat
af20: 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ed.** string con
af30: 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e  taining the tran
af40: 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d  sactions master-
af50: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d  journal file nam
af60: 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a  e. VFSes that .*
af70: 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  * do not need th
af80: 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64  is signal should
af90: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
afa0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
afb0: 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73  plications .** s
afc0: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
afd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
afe0: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
aff0: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
b000: 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73  g so may .** dis
b010: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
b020: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
b030: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
b040: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
b050: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
b060: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
b070: 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20  T_PHASETWO]].** 
b080: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b090: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
b0a0: 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  O] opcode is gen
b0b0: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
b0c0: 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  y by SQLite.** a
b0d0: 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  nd sent to the V
b0e0: 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73  FS after a trans
b0f0: 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20  action has been 
b100: 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69  committed immedi
b110: 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66  ately.** but bef
b120: 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ore the database
b130: 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46   is unlocked. VF
b140: 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  Ses that do not 
b150: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
b160: 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  .** should silen
b170: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
b180: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
b190: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
b1a0: 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
b1b0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
b1c0: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
b1d0: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
b1e0: 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a  y disrupt the .*
b1f0: 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  * operation of t
b200: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
b210: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
b220: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
b230: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b240: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
b250: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
b260: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
b270: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
b280: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
b290: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
b2a0: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
b2b0: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
b2c0: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
b2d0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
b2e0: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
b2f0: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
b300: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
b310: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
b320: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
b330: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
b340: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
b350: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
b360: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
b370: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
b380: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
b390: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
b3a0: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
b3b0: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
b3c0: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
b3d0: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
b3e0: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
b3f0: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
b400: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
b410: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
b420: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
b430: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
b440: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
b450: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
b460: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
b470: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
b480: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
b490: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
b4a0: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
b4b0: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
b4c0: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
b4d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
b4e0: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
b4f0: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
b500: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
b510: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
b520: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
b530: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
b540: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
b550: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
b560: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
b570: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
b580: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
b590: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
b5a0: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
b5b0: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
b5c0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
b5d0: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
b5e0: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
b5f0: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
b600: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
b610: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
b620: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
b630: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
b640: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
b650: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
b660: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
b670: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
b680: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b690: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
b6a0: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
b6b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
b6c0: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
b6d0: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
b6e0: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
b6f0: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
b700: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
b710: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
b720: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
b730: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
b740: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
b750: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
b760: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
b770: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
b780: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
b790: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
b7a0: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
b7b0: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
b7c0: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
b7d0: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
b7e0: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
b7f0: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
b800: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
b810: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
b820: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
b830: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
b840: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
b850: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
b860: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
b870: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
b880: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
b890: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
b8a0: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
b8b0: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
b8c0: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
b8d0: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
b8e0: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
b8f0: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
b900: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
b910: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
b920: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
b930: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
b940: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
b950: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
b960: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
b970: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
b980: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
b990: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
b9a0: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
b9b0: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
b9c0: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
b9d0: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
b9e0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
b9f0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
ba00: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
ba10: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
ba20: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
ba30: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
ba40: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ba50: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
ba60: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
ba70: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
ba80: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
ba90: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
baa0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
bab0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
bac0: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
bad0: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
bae0: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
baf0: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
bb00: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
bb10: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
bb20: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
bb30: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
bb40: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
bb50: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
bb60: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
bb70: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
bb80: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
bb90: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
bba0: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
bbb0: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
bbc0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
bbd0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
bbe0: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
bbf0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
bc00: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
bc10: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
bc20: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
bc30: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
bc40: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
bc50: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
bc60: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
bc70: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
bc80: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bc90: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
bca0: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
bcb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
bcc0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
bcd0: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
bce0: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
bcf0: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
bd00: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
bd10: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
bd20: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
bd30: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
bd40: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
bd50: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
bd60: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
bd70: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
bd80: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
bd90: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
bda0: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
bdb0: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
bdc0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
bdd0: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
bde0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
bdf0: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
be00: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
be10: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
be20: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
be30: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
be40: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
be50: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
be60: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
be70: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
be80: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
be90: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
bea0: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
beb0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
bec0: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
bed0: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
bee0: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
bef0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
bf00: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
bf10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
bf20: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
bf30: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
bf40: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
bf50: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
bf60: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
bf70: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
bf80: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
bf90: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
bfa0: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
bfb0: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
bfc0: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
bfd0: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
bfe0: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
bff0: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
c000: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
c010: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
c020: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
c030: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
c040: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
c050: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
c060: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
c070: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
c080: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
c090: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
c0a0: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
c0b0: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
c0c0: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
c0d0: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
c0e0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
c0f0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
c100: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
c110: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
c120: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
c130: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
c140: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
c150: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
c160: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
c170: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
c180: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
c190: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
c1a0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
c1b0: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
c1c0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
c1d0: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
c1e0: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
c1f0: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
c200: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
c210: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
c220: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
c230: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
c240: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
c250: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
c260: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
c270: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
c280: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
c290: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
c2a0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
c2b0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
c2c0: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
c2d0: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
c2e0: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
c2f0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
c300: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
c310: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
c320: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
c330: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
c340: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
c350: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
c360: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
c370: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
c380: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
c390: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
c3a0: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
c3b0: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
c3c0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
c3d0: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
c3e0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
c3f0: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
c400: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
c410: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
c420: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
c430: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
c440: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
c450: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
c460: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
c470: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
c480: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
c490: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
c4a0: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
c4b0: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
c4c0: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
c4d0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e  pared statement.
c4e0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
c4f0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
c500: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
c510: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
c520: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
c530: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
c540: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
c550: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
c560: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
c570: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
c580: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
c590: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
c5a0: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
c5b0: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
c5c0: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
c5d0: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
c5e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
c5f0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
c600: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
c610: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
c620: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
c630: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
c640: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
c650: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
c660: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
c670: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
c680: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c690: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
c6a0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
c6b0: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
c6c0: 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  LER].** file-con
c6d0: 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f  trol may be invo
c6e0: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  ked by SQLite on
c6f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
c700: 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f  le handle.** sho
c710: 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73  rtly after it is
c720: 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72   opened in order
c730: 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75   to provide a cu
c740: 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63  stom VFS with ac
c750: 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  cess.** to the c
c760: 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d  onnections busy-
c770: 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
c780: 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  . The argument i
c790: 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20  s of type (void 
c7a0: 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61  **).** - an arra
c7b0: 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a  y of two (void *
c7c0: 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69  ) values. The fi
c7d0: 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74  rst (void *) act
c7e0: 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20  ually points.** 
c7f0: 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
c800: 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76   type (int (*)(v
c810: 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65  oid *)). In orde
c820: 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20  r to invoke the 
c830: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62  connections.** b
c840: 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69  usy-handler, thi
c850: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  s function shoul
c860: 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  d be invoked wit
c870: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f  h the second (vo
c880: 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20  id *) in.** the 
c890: 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c  array as the onl
c8a0: 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69  y argument. If i
c8b0: 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  t returns non-ze
c8c0: 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65  ro, then the ope
c8d0: 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  ration.** should
c8e0: 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20   be retried. If 
c8f0: 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  it returns zero,
c900: 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20   the custom VFS 
c910: 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74  should abandon t
c920: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70  he.** current op
c930: 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  eration..**.** <
c940: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c950: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d  L_TEMPFILENAME]]
c960: 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e  .** ^Application
c970: 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20   can invoke the 
c980: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
c990: 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65  MPFILENAME] file
c9a0: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68  -control.** to h
c9b0: 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72  ave SQLite gener
c9c0: 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61  ate a.** tempora
c9d0: 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e  ry filename usin
c9e0: 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
c9f0: 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c  ithm that is fol
ca00: 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74  lowed to generat
ca10: 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
ca20: 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d  ilenames for TEM
ca30: 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68  P tables and oth
ca40: 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73  er internal uses
ca50: 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65  .  The.** argume
ca60: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  nt should be a c
ca70: 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  har** which will
ca80: 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20   be filled with 
ca90: 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
caa0: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
cab0: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
cac0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
cad0: 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65  c()].  The calle
cae0: 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f  r should.** invo
caf0: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
cb00: 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c  ()] on the resul
cb10: 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d  t to avoid a mem
cb20: 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20  ory leak..**.** 
cb30: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
cb40: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  TL_MMAP_SIZE]].*
cb50: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
cb60: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
cb70: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
cb80: 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20  sed to query or 
cb90: 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d  set the.** maxim
cba0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
cbb0: 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  es that will be 
cbc0: 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d  used for memory-
cbd0: 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54  mapped I/O..** T
cbe0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
cbf0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
cc00: 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69  lue of type sqli
cc10: 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a  te3_int64 that.*
cc20: 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79  * is an advisory
cc30: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
cc40: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
cc50: 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d  file to memory m
cc60: 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e  ap.  The.** poin
cc70: 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74  ter is overwritt
cc80: 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20  en with the old 
cc90: 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69  value.  The limi
cca0: 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  t is not changed
ccb0: 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65   if.** the value
ccc0: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e   originally poin
ccd0: 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69  ted to is negati
cce0: 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63  ve, and so the c
ccf0: 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a  urrent limit .**
cd00: 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20   can be queried 
cd10: 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20  by passing in a 
cd20: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67  pointer to a neg
cd30: 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54  ative number.  T
cd40: 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  his.** file-cont
cd50: 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65  rol is used inte
cd60: 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d  rnally to implem
cd70: 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  ent [PRAGMA mmap
cd80: 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  _size]..**.** <l
cd90: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
cda0: 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20  _TRACE]].** The 
cdb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
cdc0: 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ACE] file contro
cdd0: 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73  l provides advis
cde0: 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ory information.
cdf0: 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62  ** to the VFS ab
ce00: 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67  out what the hig
ce10: 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68  her layers of th
ce20: 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61  e SQLite stack a
ce30: 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69  re doing..** Thi
ce40: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
ce50: 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56  s used by some V
ce60: 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63  FS activity trac
ce70: 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20  ing [shims]..** 
ce80: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
ce90: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
cea0: 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65  d string.  Highe
ceb0: 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a  r layers in the.
cec0: 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  ** SQLite stack 
ced0: 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73  may generate ins
cee0: 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66  tances of this f
cef0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a  ile control if.*
cf00: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  * the [SQLITE_US
cf10: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63  E_FCNTL_TRACE] c
cf20: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
cf30: 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
cf40: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
cf50: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
cf60: 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  D]].** The [SQLI
cf70: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
cf80: 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ED] file control
cf90: 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20   interprets its 
cfa0: 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a  argument as a.**
cfb0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
cfc0: 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72  nteger and it wr
cfd0: 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69  ites a boolean i
cfe0: 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
cff0: 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e   depending.** on
d000: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
d010: 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65  the file has bee
d020: 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64  n renamed, moved
d030: 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e  , or deleted sin
d040: 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72  ce it.** was fir
d050: 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  st opened..**.**
d060: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
d070: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
d080: 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NDLE]].** The [S
d090: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
d0a0: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70  2_SET_HANDLE] op
d0b0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
d0c0: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
d0d0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
d0e0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
d0f0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77  rol method to sw
d100: 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64  ap the file hand
d110: 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a  le with the one.
d120: 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
d130: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
d140: 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69  nt.  This capabi
d150: 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72  lity is used dur
d160: 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61  ing testing.** a
d170: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
d180: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
d190: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69  en SQLITE_TEST i
d1a0: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  s defined..**.**
d1b0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </ul>.*/.#defin
d1c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
d1d0: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
d1e0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
d1f0: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
d200: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
d210: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
d220: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
d230: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20  ROXYFILE        
d240: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
d250: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
d260: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d270: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
d280: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
d290: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  HINT            
d2a0: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
d2b0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
d2c0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
d2d0: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
d2e0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
d2f0: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
d300: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
d310: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
d320: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20  TTED            
d330: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
d340: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
d350: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39  RETRY          9
d360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d370: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
d380: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  L            10.
d390: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d3a0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20  CNTL_OVERWRITE  
d3b0: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23              11.#
d3c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d3d0: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20  NTL_VFSNAME     
d3e0: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64             12.#d
d3f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d400: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
d410: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65  RWRITE    13.#de
d420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d430: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  L_PRAGMA        
d440: 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66           14.#def
d450: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d460: 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20  _BUSYHANDLER    
d470: 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69          15.#defi
d480: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d490: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20  TEMPFILENAME    
d4a0: 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e         16.#defin
d4b0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  e SQLITE_FCNTL_M
d4c0: 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20  MAP_SIZE        
d4d0: 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65        18.#define
d4e0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52   SQLITE_FCNTL_TR
d4f0: 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ACE             
d500: 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20       19.#define 
d510: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
d520: 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20  _MOVED          
d530: 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53      20.#define S
d540: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
d550: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d560: 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51     21.#define SQ
d570: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
d580: 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20  T_PHASETWO      
d590: 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    22.#define SQL
d5a0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
d5b0: 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20  SET_HANDLE      
d5c0: 20 32 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   23../*.** CAPI3
d5d0: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
d5e0: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  e.**.** The mute
d5f0: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
d600: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
d610: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
d620: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
d630: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
d640: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
d650: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
d660: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
d670: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
d680: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
d690: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
d6a0: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
d6b0: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
d6c0: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
d6d0: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
d6e0: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
d6f0: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
d700: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
d710: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
d720: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
d730: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
d740: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
d750: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
d760: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
d770: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
d780: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
d790: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
d7a0: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
d7b0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
d7c0: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
d7d0: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
d7e0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
d7f0: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
d800: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
d810: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
d820: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
d830: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
d840: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
d850: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
d860: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
d870: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
d880: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  The value of the
d890: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
d8a0: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
d8b0: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
d8c0: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65   in.** future ve
d8d0: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
d8e0: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
d8f0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
d900: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
d910: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
d920: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
d930: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f  s increased.  No
d940: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
d950: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
d960: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
d970: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
d980: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
d990: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  tween.** SQLite 
d9a0: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e  version 3.5.9 an
d9b0: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20  d 3.6.0 and yet 
d9c0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
d9d0: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f  ld was not.** mo
d9e0: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
d9f0: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
da00: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
da10: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
da20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
da30: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
da40: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
da50: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
da60: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
da70: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
da80: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
da90: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
daa0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
dab0: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
dac0: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
dad0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
dae0: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
daf0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
db00: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
db10: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
db20: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
db30: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
db40: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
db50: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
db60: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
db70: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
db80: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
db90: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
dba0: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
dbb0: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
dbc0: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
dbd0: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
dbe0: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
dbf0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
dc00: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
dc10: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
dc20: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
dc30: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
dc40: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
dc50: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
dc60: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
dc70: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
dc80: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
dc90: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
dca0: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
dcb0: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
dcc0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
dcd0: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
dce0: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
dcf0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
dd00: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
dd10: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
dd20: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
dd30: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
dd40: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
dd50: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
dd60: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
dd70: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
dd80: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
dd90: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73  dules..**.** [[s
dda0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
ddb0: 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  ]].** ^SQLite gu
ddc0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
ddd0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
dde0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
ddf0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
de00: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
de10: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
de20: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
de30: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
de40: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
de50: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
de60: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
de70: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
de80: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
de90: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
dea0: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
deb0: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
dec0: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
ded0: 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72  ** 11 alphanumer
dee0: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
def0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
df00: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
df10: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
df20: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
df30: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
df40: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
df50: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
df60: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
df70: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
df80: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
df90: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
dfa0: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
dfb0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
dfc0: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
dfd0: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
dfe0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
dff0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
e000: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
e010: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
e020: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
e030: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
e040: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
e050: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
e060: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
e070: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
e080: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
e090: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
e0a0: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
e0b0: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
e0c0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
e0d0: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
e0e0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
e0f0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
e100: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
e110: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
e120: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
e130: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
e140: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
e150: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
e160: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
e170: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
e180: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
e190: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
e1a0: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
e1b0: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
e1c0: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
e1d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
e1e0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
e1f0: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
e200: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
e210: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
e220: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
e230: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
e240: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
e250: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
e260: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
e270: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
e280: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
e290: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
e2a0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
e2b0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
e2c0: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
e2d0: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
e2e0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
e2f0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
e300: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
e310: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
e320: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
e330: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
e340: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
e350: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
e360: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
e370: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
e380: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
e390: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e3a0: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
e3b0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e3c0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
e3d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
e3e0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
e3f0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
e400: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
e410: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
e420: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
e430: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e440: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
e450: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
e460: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
e470: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
e480: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
e490: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
e4a0: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
e4b0: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
e4c0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
e4d0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
e4e0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
e4f0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
e500: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
e510: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
e520: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
e530: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
e540: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
e550: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
e560: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
e570: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
e580: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
e590: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
e5a0: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
e5b0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
e5c0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
e5d0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
e5e0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
e5f0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
e600: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
e610: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
e620: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
e630: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
e640: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
e650: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
e660: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
e670: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
e680: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
e690: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
e6a0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
e6b0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
e6c0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
e6d0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
e6e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
e6f0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
e700: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
e710: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
e720: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
e730: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
e740: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
e750: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
e760: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
e770: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
e780: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
e790: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
e7a0: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
e7b0: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
e7c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
e7d0: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
e7e0: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
e7f0: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
e800: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
e810: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
e820: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
e830: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
e840: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
e850: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
e860: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
e870: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
e880: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
e890: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
e8a0: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
e8b0: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
e8c0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
e8d0: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
e8e0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
e8f0: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
e900: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
e910: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
e920: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
e930: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
e940: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
e950: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
e960: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
e970: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
e980: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
e990: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
e9a0: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
e9b0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
e9c0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
e9d0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
e9e0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
e9f0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
ea00: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
ea10: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
ea20: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
ea30: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
ea40: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
ea50: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
ea60: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
ea70: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
ea80: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
ea90: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
eaa0: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
eab0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
eac0: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
ead0: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
eae0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
eaf0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
eb00: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
eb10: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
eb20: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
eb30: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
eb40: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
eb50: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
eb60: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
eb70: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
eb80: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
eb90: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
eba0: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
ebb0: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
ebc0: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b  en call..**.** [
ebd0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63  [sqlite3_vfs.xAc
ebe0: 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66  cess]].** ^The f
ebf0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
ec00: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
ec10: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
ec20: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74  _EXISTS].** to t
ec30: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
ec40: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tence of a file,
ec50: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
ec60: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f  SS_READWRITE] to
ec70: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72  .** test whether
ec80: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
ec90: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
eca0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
ecb0: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
ecc0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
ecd0: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
ece0: 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20  readable.   The 
ecf0: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
ed00: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
ed10: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  * ^SQLite will a
ed20: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
ed30: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
ed40: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
ed50: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
ed60: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
ed70: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69  e.  The exact si
ed80: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
ed90: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
eda0: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
edb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
edc0: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68    methods. If th
edd0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
ede0: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
edf0: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
ee00: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
ee10: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
ee20: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
ee30: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
ee40: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
ee50: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
ee60: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
ee70: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
ee80: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
ee90: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
eea0: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
eeb0: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
eec0: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
eed0: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
eee0: 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  , xCurrentTime()
eef0: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
ef00: 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74  meInt64().** int
ef10: 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20  erfaces are not 
ef20: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
ef30: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
ef40: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
ef50: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
ef60: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
ef70: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
ef80: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
ef90: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
efa0: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
efb0: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
efc0: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
efd0: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
efe0: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
eff0: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
f000: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
f010: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
f020: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
f030: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
f040: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
f050: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
f060: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
f070: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
f080: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
f090: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
f0a0: 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54    ^The xCurrentT
f0b0: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ime().** method 
f0c0: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e  returns a Julian
f0d0: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20   Day Number for 
f0e0: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65  the current date
f0f0: 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20   and time as.** 
f100: 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
f110: 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20   value..** ^The 
f120: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
f130: 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  4() method retur
f140: 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65  ns, as an intege
f150: 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a  r, the Julian.**
f160: 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74   Day Number mult
f170: 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30  iplied by 864000
f180: 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f  00 (the number o
f190: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69  f milliseconds i
f1a0: 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20  n .** a 24-hour 
f1b0: 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69  day).  .** ^SQLi
f1c0: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
f1d0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
f1e0: 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65  4() method to ge
f1f0: 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  t the current.**
f200: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69   date and time i
f210: 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73  f that method is
f220: 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69   available (if i
f230: 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20  Version is 2 or 
f240: 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20  .** greater and 
f250: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
f260: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
f270: 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20  ) and will fall 
f280: 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72  back.** to xCurr
f290: 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75  entTime() if xCu
f2a0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
f2b0: 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
f2c0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74  .**.** ^The xSet
f2d0: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47  SystemCall(), xG
f2e0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
f2f0: 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43  and xNestSystemC
f300: 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73  all() interfaces
f310: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64  .** are not used
f320: 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63   by the SQLite c
f330: 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69  ore.  These opti
f340: 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  onal interfaces 
f350: 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  are provided.** 
f360: 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f  by some VFSes to
f370: 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74   facilitate test
f380: 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63  ing of the VFS c
f390: 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69  ode. By overridi
f3a0: 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61  ng .** system ca
f3b0: 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f  lls with functio
f3c0: 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e  ns under its con
f3d0: 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f  trol, a test pro
f3e0: 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75  gram can.** simu
f3f0: 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20  late faults and 
f400: 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73  error conditions
f410: 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65   that would othe
f420: 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75  rwise be difficu
f430: 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69  lt.** or impossi
f440: 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20  ble to induce.  
f450: 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65  The set of syste
f460: 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e  m calls that can
f470: 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a   be overridden.*
f480: 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  * varies from on
f490: 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72  e VFS to another
f4a0: 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76  , and from one v
f4b0: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61  ersion of the sa
f4c0: 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a  me VFS to the.**
f4d0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
f4e0: 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68  ions that use th
f4f0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
f500: 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20  ust be prepared 
f510: 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c  for any.** or al
f520: 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72  l of these inter
f530: 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c  faces to be NULL
f540: 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65   or for their be
f550: 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65  havior to change
f560: 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c  .** from one rel
f570: 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74  ease to the next
f580: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
f590: 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74  must not attempt
f5a0: 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e   to access.** an
f5b0: 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f  y of these metho
f5c0: 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69  ds if the iVersi
f5d0: 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73  on of the VFS is
f5e0: 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f   less than 3..*/
f5f0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
f600: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
f610: 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66  te3_vfs;.typedef
f620: 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
f630: 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69  syscall_ptr)(voi
f640: 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  d);.struct sqlit
f650: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
f660: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
f670: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
f680: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
f690: 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f  (currently 3) */
f6a0: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
f6b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
f6c0: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
f6d0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
f6e0: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
f6f0: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
f700: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
f710: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
f720: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
f730: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
f740: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
f750: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
f760: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
f770: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
f780: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
f790: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
f7a0: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
f7b0: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
f7c0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
f7d0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
f7e0: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
f7f0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f800: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
f810: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
f820: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
f830: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
f840: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
f850: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
f860: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
f870: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
f880: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
f890: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
f8a0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
f8b0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
f8c0: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
f8d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
f8e0: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
f8f0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
f900: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
f910: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
f920: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
f930: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
f940: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
f950: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
f960: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
f970: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
f980: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
f990: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a  rMsg);.  void (*
f9a0: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
f9b0: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
f9c0: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
f9d0: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69  l))(void);.  voi
f9e0: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71  d (*xDlClose)(sq
f9f0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64  lite3_vfs*, void
fa00: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e  *);.  int (*xRan
fa10: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33  domness)(sqlite3
fa20: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
fa30: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
fa40: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73   int (*xSleep)(s
fa50: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
fa60: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a   microseconds);.
fa70: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
fa80: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Time)(sqlite3_vf
fa90: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20  s*, double*);.  
faa0: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72  int (*xGetLastEr
fab0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
fac0: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b  *, int, char *);
fad0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
fae0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
faf0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66   in version 1 of
fb00: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
fb10: 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69  object.  ** defi
fb20: 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74  nition.  Those t
fb30: 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61  hat follow are a
fb40: 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20  dded in version 
fb50: 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a  2 or later.  */.
fb60: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
fb70: 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74  TimeInt64)(sqlit
fb80: 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33  e3_vfs*, sqlite3
fb90: 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20  _int64*);.  /*. 
fba0: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
fbb0: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
fbc0: 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66  sions 1 and 2 of
fbd0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
fbe0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f  object..  ** Tho
fbf0: 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72  se below are for
fc00: 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67   version 3 and g
fc10: 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69  reater..  */.  i
fc20: 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43  nt (*xSetSystemC
fc30: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
fc40: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
fc50: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79  Name, sqlite3_sy
fc60: 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71  scall_ptr);.  sq
fc70: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
fc80: 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61  r (*xGetSystemCa
fc90: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
fca0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
fcb0: 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68  ame);.  const ch
fcc0: 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65  ar *(*xNextSyste
fcd0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
fce0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
fcf0: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20  *zName);.  /*.  
fd00: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
fd10: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
fd20: 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33  ions 1 through 3
fd30: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
fd40: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
fd50: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
fd60: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69  e appended in fi
fd70: 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  gure versions.  
fd80: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
fd90: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
fda0: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
fdb0: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20  this happens. . 
fdc0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
fdd0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
fde0: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46  r the xAccess VF
fdf0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
fe00: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
fe10: 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73  stants can be us
fe20: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
fe30: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
fe40: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
fe50: 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  od of an [sqlite
fe60: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
fe70: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
fe80: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70  * what kind of p
fe90: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78  ermissions the x
fea0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73  Access method is
feb0: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a   looking for..**
fec0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
fed0: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
fee0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
fef0: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
ff00: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
ff10: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68   exists..** With
ff20: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
ff30: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41  EADWRITE, the xA
ff40: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
ff50: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
ff60: 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f  he named directo
ff70: 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61  ry is both reada
ff80: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
ff90: 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f  .** (in other wo
ffa0: 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61  rds, if files ca
ffb0: 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f  n be added, remo
ffc0: 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64  ved, and renamed
ffd0: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64   within.** the d
ffe0: 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68  irectory)..** Th
fff0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
10000 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61  READWRITE consta
10010 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  nt is currently 
10020 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65  used only by the
10030 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  .** [temp_store_
10040 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
10050 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63  ], though this c
10060 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61  ould change in a
10070 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
10080 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
10090 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
100a0 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
100b0 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
100c0 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
100d0 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
100e0 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ble.  The SQLITE
100f0 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e  _ACCESS_READ con
10100 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72  stant is.** curr
10110 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68  ently unused, th
10120 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65  ough it might be
10130 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72   used in a futur
10140 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
10150 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
10160 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
10170 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
10180 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
10190 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20  SS_READWRITE 1  
101a0 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47   /* Used by PRAG
101b0 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  MA temp_store_di
101c0 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69  rectory */.#defi
101d0 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
101e0 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f  _READ      2   /
101f0 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  * Unused */../*.
10200 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
10210 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c  gs for the xShmL
10220 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ock VFS method.*
10230 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
10240 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  er constants def
10250 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20  ine the various 
10260 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f  locking operatio
10270 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79  ns.** allowed by
10280 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   the xShmLock me
10290 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  thod of [sqlite3
102a0 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54  _io_methods].  T
102b0 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
102c0 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67  are the only leg
102d0 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  al combinations 
102e0 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a  of flags to the.
102f0 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  ** xShmLock meth
10300 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
10310 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
10320 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
10330 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
10340 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
10350 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
10360 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
10370 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
10380 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
10390 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
103a0 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
103b0 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
103c0 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
103d0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  </ul>.**.** When
103e0 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20   unlocking, the 
103f0 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45  same SHARED or E
10400 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75  XCLUSIVE flag mu
10410 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61  st be supplied a
10420 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6f  s.** was given o
10430 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
10440 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a  ing lock.  .**.*
10450 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
10460 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69  ethod can transi
10470 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c  tion between unl
10480 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44  ocked and SHARED
10490 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75   or.** between u
104a0 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c  nlocked and EXCL
104b0 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f  USIVE.  It canno
104c0 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  t transition bet
104d0 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61  ween SHARED.** a
104e0 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f  nd EXCLUSIVE..*/
104f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10500 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  SHM_UNLOCK      
10510 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
10520 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20  E_SHM_LOCK      
10530 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
10540 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20  ITE_SHM_SHARED  
10550 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
10560 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10570 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20  IVE    8../*.** 
10580 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75  CAPI3REF: Maximu
10590 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78  m xShmLock index
105a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
105b0 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73  ock method on [s
105c0 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
105d0 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65  s] may use value
105e0 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61  s.** between 0 a
105f0 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f  nd this upper bo
10600 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73  und as its "offs
10610 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  et" argument..**
10620 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
10630 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65   will never atte
10640 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f  mpt to acquire o
10650 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c  r release a.** l
10660 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74  ock outside of t
10670 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65  his range.*/.#de
10680 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
10690 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a  NLOCK        8..
106a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
106b0 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
106c0 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
106d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
106e0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
106f0 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
10700 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
10710 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
10720 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10730 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
10740 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
10750 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
10760 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
10770 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10780 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
10790 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
107a0 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
107b0 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
107c0 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
107d0 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
107e0 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
107f0 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
10800 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
10810 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
10820 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
10830 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
10840 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
10850 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
10860 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10870 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
10880 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
10890 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
108a0 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
108b0 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
108c0 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
108d0 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
108e0 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
108f0 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
10900 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
10910 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
10920 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
10930 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
10940 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
10950 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
10960 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
10970 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10980 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
10990 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
109a0 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
109b0 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
109c0 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
109d0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
109e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
109f0 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
10a00 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
10a10 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
10a20 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
10a30 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
10a40 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
10a50 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
10a60 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
10a70 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
10a80 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
10a90 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
10aa0 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
10ab0 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
10ac0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
10ad0 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
10ae0 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
10af0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10b00 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
10b10 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
10b20 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
10b30 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
10b40 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
10b50 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
10b60 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
10b70 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
10b80 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
10b90 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
10ba0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10bb0 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
10bc0 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
10bd0 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
10be0 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
10bf0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
10c00 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
10c10 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
10c20 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
10c30 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
10c40 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
10c50 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
10c60 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
10c70 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
10c80 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
10c90 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
10ca0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
10cb0 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
10cc0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
10cd0 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
10ce0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
10cf0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
10d00 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
10d10 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
10d20 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
10d30 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
10d40 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
10d50 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
10d60 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
10d70 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
10d80 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
10d90 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
10da0 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
10db0 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
10dc0 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
10dd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
10de0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10df0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
10e00 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
10e10 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
10e20 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
10e30 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
10e40 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
10e50 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
10e60 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
10e70 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
10e80 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
10e90 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
10ea0 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
10eb0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10ec0 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
10ed0 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
10ee0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
10ef0 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
10f00 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
10f10 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
10f20 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
10f30 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
10f40 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
10f50 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
10f60 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
10f70 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
10f80 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
10f90 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
10fa0 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
10fb0 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
10fc0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10fd0 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
10fe0 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
10ff0 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
11000 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11010 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
11020 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
11030 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
11040 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
11050 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
11060 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
11070 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
11080 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
11090 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
110a0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
110b0 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
110c0 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
110d0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
110e0 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
110f0 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
11100 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
11110 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
11120 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
11130 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
11140 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
11150 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
11160 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
11170 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
11180 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
11190 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
111a0 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
111b0 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
111c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
111d0 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
111e0 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
111f0 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
11200 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
11210 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
11220 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
11230 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
11240 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
11250 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
11260 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11270 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
11280 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
11290 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
112a0 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
112b0 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
112c0 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
112d0 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
112e0 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
112f0 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
11300 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
11310 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
11320 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
11330 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
11340 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
11350 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
11360 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
11370 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
11380 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
11390 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
113a0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
113b0 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
113c0 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
113d0 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
113e0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
113f0 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
11400 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11410 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
11420 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
11430 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
11440 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
11450 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
11460 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
11470 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
11480 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
11490 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
114a0 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
114b0 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
114c0 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
114d0 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
114e0 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
114f0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
11500 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
11510 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
11520 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
11530 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
11540 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
11550 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
11560 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
11570 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
11580 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
11590 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
115a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
115b0 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
115c0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
115d0 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
115e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
115f0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
11600 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
11610 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
11620 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
11630 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
11640 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
11650 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
11660 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
11670 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
11680 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
11690 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
116a0 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
116b0 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
116c0 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  re..*/.SQLITE_AP
116d0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e  I int sqlite3_in
116e0 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a  itialize(void);.
116f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
11700 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11710 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
11720 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  I int sqlite3_os
11730 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c  _init(void);.SQL
11740 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
11750 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
11760 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11770 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
11780 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
11790 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
117a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
117b0 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
117c0 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
117d0 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
117e0 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
117f0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
11800 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
11810 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
11820 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
11830 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
11840 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
11850 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
11860 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
11870 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
11880 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
11890 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
118a0 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
118b0 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
118c0 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
118d0 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
118e0 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
118f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
11900 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
11910 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
11920 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
11930 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
11940 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
11950 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
11960 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
11970 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
11980 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
11990 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
119a0 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
119b0 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
119c0 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
119d0 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
119e0 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
119f0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
11a00 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
11a10 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
11a20 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
11a30 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
11a40 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
11a50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
11a60 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
11a70 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11a80 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
11a90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
11aa0 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
11ab0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
11ac0 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
11ad0 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
11ae0 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
11af0 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
11b00 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
11b10 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
11b20 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
11b30 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
11b40 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11b50 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
11b60 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
11b70 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11b80 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
11b90 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
11ba0 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
11bb0 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
11bc0 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
11bd0 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
11be0 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
11bf0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
11c00 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
11c10 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
11c20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
11c30 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
11c40 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
11c50 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
11c60 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
11c70 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
11c80 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
11c90 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
11ca0 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
11cb0 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
11cc0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
11cd0 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
11ce0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
11cf0 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
11d00 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
11d10 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
11d20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
11d30 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
11d40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
11d50 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
11d60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
11d70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11d80 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
11d90 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
11da0 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
11db0 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
11dc0 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
11dd0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
11de0 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
11df0 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
11e00 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
11e10 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
11e20 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
11e30 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
11e40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11e50 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
11e60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11e70 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
11e80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
11e90 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
11ea0 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
11eb0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
11ec0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
11ed0 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
11ee0 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
11ef0 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
11f00 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
11f10 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
11f20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11f30 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
11f40 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
11f50 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
11f60 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
11f70 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
11f80 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
11f90 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
11fa0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11fb0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
11fc0 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
11fd0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
11fe0 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
11ff0 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ssful..*/.SQLITE
12000 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
12010 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
12020 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
12030 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12040 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
12050 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
12060 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
12070 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
12080 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
12090 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
120a0 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
120b0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
120c0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
120d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
120e0 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
120f0 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
12100 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
12110 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
12120 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
12130 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12140 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
12150 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
12160 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
12170 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
12180 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
12190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
121a0 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
121b0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
121c0 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
121d0 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
121e0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
121f0 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
12200 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
12210 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
12220 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
12230 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
12240 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
12250 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
12260 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
12270 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
12280 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
12290 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
122a0 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
122b0 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
122c0 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
122d0 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
122e0 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
122f0 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
12300 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
12310 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
12320 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
12330 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
12340 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
12350 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
12360 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
12370 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
12380 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
12390 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
123a0 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
123b0 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
123c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
123d0 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
123e0 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
123f0 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
12400 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
12410 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
12420 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
12430 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
12440 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
12450 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
12460 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
12470 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
12480 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
12490 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
124a0 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
124b0 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
124c0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
124d0 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c   xMalloc, xReall
124e0 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65  oc, and xFree me
124f0 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
12500 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
12510 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
12520 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
12530 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
12540 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
12550 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ..** ^SQLite gua
12560 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
12570 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
12580 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
12590 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
125a0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
125b0 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
125c0 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53  oundup..**.** xS
125d0 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
125e0 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
125f0 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
12600 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
12610 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
12620 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
12630 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
12640 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
12650 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
12660 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
12670 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
12680 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
12690 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
126a0 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
126b0 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
126c0 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
126d0 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
126e0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
126f0 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
12700 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
12710 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
12720 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
12730 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
12740 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
12750 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
12760 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
12770 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
12780 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
12790 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
127a0 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
127b0 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
127c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
127d0 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
127e0 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
127f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
12800 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
12810 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
12820 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
12830 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
12840 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
12850 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
12860 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
12870 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
12880 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
12890 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
128a0 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
128b0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46  ry allocator.  F
128c0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
128d0 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
128e0 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
128f0 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
12900 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
12910 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
12920 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
12930 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
12940 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
12950 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
12960 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
12970 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
12980 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
12990 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
129a0 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
129b0 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
129c0 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
129d0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
129e0 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
129f0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
12a00 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
12a10 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
12a20 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
12a30 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
12a40 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
12a50 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
12a60 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
12a70 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
12a80 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
12a90 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
12aa0 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
12ab0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
12ac0 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
12ad0 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
12ae0 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
12af0 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
12b00 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
12b10 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
12b20 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
12b30 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
12b40 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
12b50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
12b60 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
12b70 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
12b80 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
12b90 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
12ba0 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
12bb0 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
12bc0 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
12bd0 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
12be0 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
12bf0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
12c00 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
12c10 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
12c20 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
12c30 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
12c40 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
12c50 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
12c60 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
12c70 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
12c80 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
12c90 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
12ca0 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
12cb0 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
12cc0 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
12cd0 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
12ce0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
12cf0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
12d00 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12d10 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
12d20 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
12d30 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
12d40 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
12d50 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
12d60 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
12d70 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
12d80 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
12d90 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
12da0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
12db0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
12dc0 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
12dd0 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
12de0 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
12df0 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
12e00 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
12e10 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
12e20 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
12e30 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
12e40 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
12e50 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
12e60 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
12e70 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
12e80 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
12e90 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
12ea0 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
12eb0 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
12ec0 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
12ed0 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
12ee0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
12ef0 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
12f00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
12f10 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
12f20 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
12f30 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
12f40 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
12f50 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
12f60 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
12f70 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
12f80 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
12f90 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
12fa0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
12fb0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
12fc0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
12fd0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
12fe0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12ff0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
13000 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
13010 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13020 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
13030 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
13040 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
13050 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13060 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
13070 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
13080 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
13090 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
130a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
130b0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
130c0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
130d0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
130e0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
130f0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
13100 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
13110 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
13120 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
13130 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
13140 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
13150 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
13160 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
13170 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
13180 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
13190 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
131a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
131b0 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
131c0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
131d0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
131e0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
131f0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13200 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
13210 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
13220 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
13230 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
13240 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
13250 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
13260 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
13270 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
13280 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
13290 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
132a0 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
132b0 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
132c0 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
132d0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
132e0 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
132f0 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
13300 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13310 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
13320 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13330 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
13340 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
13350 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
13360 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
13370 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
13380 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
13390 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
133a0 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
133b0 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
133c0 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
133d0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
133e0 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
133f0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
13400 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
13410 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
13420 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
13430 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
13440 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
13460 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
13470 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
13480 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
13490 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
134a0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
134b0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
134c0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
134d0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
134e0 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
134f0 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
13500 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
13510 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
13520 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
13530 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
13540 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
13550 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
13560 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
13570 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
13580 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
13590 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
135a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
135b0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
135c0 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
135d0 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
135e0 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
135f0 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
13600 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
13610 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
13620 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
13630 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
13640 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
13650 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
13660 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
13670 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
13680 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
13690 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
136a0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
136b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
136c0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
136d0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
136e0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
136f0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
13700 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
13710 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
13720 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
13730 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
13740 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13750 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
13760 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
13770 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
13780 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
13790 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
137a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
137b0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
137c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
137d0 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
137e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
137f0 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
13800 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
13810 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
13820 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
13830 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
13840 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
13850 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
13860 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
13870 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
13880 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
13890 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
138a0 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
138b0 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
138c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
138d0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
138e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
138f0 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
13900 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
13910 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
13920 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13930 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
13940 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
13950 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
13960 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
13970 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
13980 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
13990 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
139a0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
139b0 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
139c0 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
139d0 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
139e0 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
139f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13a00 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
13a10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
13a20 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
13a30 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
13a40 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
13a50 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13a60 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13a70 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13a80 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13a90 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13aa0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13ab0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
13ac0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
13ad0 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
13ae0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
13af0 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
13b00 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
13b10 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
13b20 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
13b30 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
13b40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
13b50 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
13b60 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
13b70 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13b80 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
13b90 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13ba0 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
13bb0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
13bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
13bd0 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
13be0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13bf0 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
13c00 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
13c10 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
13c20 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
13c30 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
13c40 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
13c50 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
13c60 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
13c70 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
13c80 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
13c90 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
13ca0 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
13cb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
13cc0 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
13cd0 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
13ce0 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
13cf0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
13d00 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
13d10 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
13d20 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
13d30 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
13d40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
13d50 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
13d60 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
13d70 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13d80 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
13d90 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
13da0 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
13db0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
13dc0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
13dd0 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
13de0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13df0 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
13e00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
13e10 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
13e20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
13e30 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
13e40 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
13e50 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
13e60 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
13e70 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
13e80 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
13e90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13ea0 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
13eb0 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
13ec0 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
13ed0 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
13ee0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13ef0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
13f00 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
13f10 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
13f20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13f30 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
13f40 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
13f50 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
13f60 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13f70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
13f80 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
13f90 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
13fa0 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
13fb0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
13fc0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70  FIG_MEMSTATUS op
13fd0 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
13fe0 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
13ff0 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72  pe int,.** inter
14000 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
14010 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
14020 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
14030 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
14040 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
14050 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
14060 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
14070 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
14080 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73  stics are.** dis
14090 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f  abled, the follo
140a0 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
140b0 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
140c0 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
140d0 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
140e0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
140f0 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
14100 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
14110 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
14120 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
14130 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
14140 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
14150 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
14160 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
14170 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
14180 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
14190 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
141a0 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
141b0 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
141c0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
141d0 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
141e0 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
141f0 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
14200 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
14210 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
14220 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
14230 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
14240 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14250 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
14260 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
14270 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
14280 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
14290 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74  NFIG_SCRATCH opt
142a0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
142b0 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
142c0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ffer.** that SQL
142d0 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20  ite can use for 
142e0 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
142f0 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72   ^(There are thr
14300 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  ee arguments.** 
14310 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
14320 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69  _SCRATCH:  A poi
14330 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
14340 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
14350 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
14360 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
14370 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
14380 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
14390 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
143a0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
143b0 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
143c0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
143d0 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
143e0 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a  cations (N).)^.*
143f0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
14400 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
14410 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
14420 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
14430 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
14440 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
14450 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
14460 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20  te will not use 
14470 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63  more than one sc
14480 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65  ratch buffers pe
14490 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51  r thread..** ^SQ
144a0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
144b0 72 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63  request a scratc
144c0 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
144d0 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
144e0 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
144f0 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a  se page size..**
14500 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
14510 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
14520 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
14530 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
14540 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
14550 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
14560 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
14570 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
14580 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
14590 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
145a0 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
145b0 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  <p>.** ^When the
145c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f   application pro
145d0 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74  vides any amount
145e0 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f   of scratch memo
145f0 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49  ry using.** SQLI
14600 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
14610 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73  H, SQLite avoids
14620 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72   unnecessary lar
14630 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  ge.** [sqlite3_m
14640 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63  alloc|heap alloc
14650 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73  ations]..** This
14660 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f   can help [Robso
14670 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20  n proof|prevent 
14680 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14690 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20  n failures] due 
146a0 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d  to heap.** fragm
146b0 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d  entation in low-
146c0 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20  memory embedded 
146d0 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64  systems..** </dd
146e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
146f0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14700 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
14710 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
14720 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
14730 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14740 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e  PAGECACHE option
14750 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
14760 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
14770 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  r.** that SQLite
14780 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65   can use for the
14790 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
147a0 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
147b0 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61  fault page.** ca
147c0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
147d0 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
147e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
147f0 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
14800 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
14810 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
14820 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
14830 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
14840 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
14850 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
14860 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
14870 6e 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68  n option..** ^Th
14880 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
14890 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
148a0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
148b0 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  HE: A pointer to
148c0 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e  .** 8-byte align
148d0 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  ed.** memory, th
148e0 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
148f0 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
14900 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
14910 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
14920 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
14930 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
14940 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
14950 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
14960 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
14970 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
14980 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20  and 65536) plus 
14990 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73  some extra bytes
149a0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
149b0 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
149c0 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20  number of extra 
149d0 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20  bytes needed by 
149e0 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a  the page header.
149f0 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
14a00 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ined using the [
14a10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14a20 41 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69  ACHE_HDRSZ] opti
14a30 6f 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  on .** to [sqlit
14a40 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
14a50 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
14a60 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
14a70 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
14a80 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61  ** for the sz pa
14a90 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61  rameter to be la
14aa0 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73  rger than necess
14ab0 61 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a  ary.  The first.
14ac0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
14ad0 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ld pointer to an
14ae0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
14af0 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
14b00 74 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65  that.** is at le
14b10 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
14b20 66 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77  f memory, otherw
14b30 69 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62  ise subsequent b
14b40 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
14b50 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c  defined..** ^SQL
14b60 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
14b70 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
14b80 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
14b90 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
14ba0 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
14bb0 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
14bc0 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
14bd0 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
14be0 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  e.  ^If addition
14bf0 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
14c00 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
14c10 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
14c20 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
14c30 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
14c40 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
14c50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14c60 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
14c70 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
14c80 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  pace.</dd>.**.**
14c90 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14ca0 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
14cb0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
14cc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
14cd0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
14ce0 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  EAP option speci
14cf0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
14d00 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20  mory buffer .** 
14d10 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
14d20 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
14d30 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
14d40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
14d50 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68  eds.** beyond th
14d60 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72  ose provided for
14d70 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
14d80 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a  IG_SCRATCH] and.
14d90 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
14da0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
14db0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14dc0 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
14dd0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
14de0 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
14df0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
14e00 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
14e10 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
14e20 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
14e30 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65  _MEMSYS5] and re
14e40 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
14e50 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b  _ERROR] if invok
14e60 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
14e70 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
14e80 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
14e90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
14ea0 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20  P:.** An 8-byte 
14eb0 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
14ec0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
14ed0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
14ee0 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
14ef0 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
14f00 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
14f10 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
14f20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
14f30 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
14f40 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
14f50 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
14f60 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
14f70 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
14f80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
14f90 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
14fa0 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
14fb0 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
14fc0 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
14fd0 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
14fe0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
14ff0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
15000 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
15010 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68  not NULL then th
15020 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
15030 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
15040 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
15050 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
15060 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
15070 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
15080 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
15090 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
150a0 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
150b0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
150c0 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
150d0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
150e0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
150f0 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
15100 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
15110 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
15120 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
15130 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
15140 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
15150 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
15160 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
15170 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
15180 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
15190 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
151a0 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
151b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
151c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
151d0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
151e0 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  _MUTEX option ta
151f0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15200 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
15210 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
15220 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
15230 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
15240 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15250 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
15260 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61  ment specifies a
15270 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
15280 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
15290 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a  nes to be used.*
152a0 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d  * in place the m
152b0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
152c0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
152d0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
152e0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
152f0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
15300 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
15310 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15320 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
15330 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
15340 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
15350 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
15360 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
15370 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
15380 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
15390 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
153a0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
153b0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
153c0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
153d0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
153e0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
153f0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
15400 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
15410 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
15420 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
15430 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
15440 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15450 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
15460 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
15470 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15480 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15490 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
154a0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
154b0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
154c0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
154d0 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69  IG_GETMUTEX opti
154e0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
154f0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
15500 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
15510 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
15520 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
15530 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
15540 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
15550 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
15560 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
15570 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
15580 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
15590 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
155a0 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
155b0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
155c0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
155d0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
155e0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
155f0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
15600 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
15610 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
15620 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
15630 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
15640 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
15650 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
15660 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
15670 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
15680 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
15690 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
156a0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
156b0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
156c0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
156d0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
156e0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
156f0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
15700 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
15710 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
15720 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
15730 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15740 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
15750 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
15760 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
15770 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
15780 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15790 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
157a0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
157b0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
157c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
157d0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
157e0 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f  _LOOKASIDE optio
157f0 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
15800 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
15810 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61  mine.** the defa
15820 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b  ult size of look
15830 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20  aside memory on 
15840 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
15850 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
15860 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15870 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
15880 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
15890 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
158a0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
158b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
158c0 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
158d0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
158e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
158f0 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49    ^(SQLITE_CONFI
15900 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73  G_LOOKASIDE.** s
15910 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75  ets the <i>defau
15920 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
15930 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
15940 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
15950 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e  ASIDE].** option
15960 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
15970 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
15980 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
15990 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
159a0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
159b0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
159c0 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
159d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
159e0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
159f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15a00 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
15a10 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
15a20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15a30 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
15a40 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15a50 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
15a60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
15a70 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
15a80 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
15a90 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
15aa0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
15ab0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20   interface to a 
15ac0 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
15ad0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
15ae0 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d  .)^.** ^SQLite m
15af0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
15b00 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  he [sqlite3_pcac
15b10 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
15b20 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
15b30 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15b40 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
15b50 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
15b60 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
15b70 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
15b80 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15b90 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
15ba0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15bb0 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
15bc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
15bd0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
15be0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
15bf0 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
15c00 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72  s of.** the curr
15c10 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ent page cache i
15c20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
15c30 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
15c40 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
15c50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15c60 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
15c70 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
15c80 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
15c90 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
15ca0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
15cb0 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
15cc0 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
15cd0 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
15ce0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15cf0 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
15d00 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
15d10 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
15d20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
15d30 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
15d40 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
15d50 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
15d60 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
15d70 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
15d80 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
15d90 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
15da0 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
15db0 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
15dc0 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
15dd0 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
15de0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
15df0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
15e00 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
15e10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
15e20 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
15e30 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
15e40 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
15e50 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
15e60 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15e70 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
15e80 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
15e90 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
15ea0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15eb0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
15ec0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
15ed0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
15ee0 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
15ef0 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
15f00 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
15f10 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
15f20 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
15f30 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
15f40 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
15f50 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
15f60 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
15f70 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
15f80 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
15f90 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
15fa0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
15fb0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
15fc0 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
15fd0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
15fe0 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
15ff0 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
16000 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
16010 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
16020 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
16030 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
16040 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
16050 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
16060 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
16070 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
16080 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
16090 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
160a0 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
160b0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
160c0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
160d0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
160e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
160f0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
16100 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
16110 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
16120 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16130 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
16140 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16150 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
16160 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16170 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _URI option take
16180 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
16190 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
161a0 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  .** If non-zero,
161b0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
161c0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
161d0 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
161e0 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
161f0 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61  ,.** then URI ha
16200 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
16210 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
16220 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
16230 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65  is globally.** e
16240 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
16250 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20  names passed to 
16260 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
16270 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
16280 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
16290 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
162a0 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
162b0 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
162c0 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
162d0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
162e0 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
162f0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
16300 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
16310 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
16320 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
16330 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
16340 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
16350 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
16360 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
16370 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
16380 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
16390 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
163a0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
163b0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
163c0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
163d0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
163e0 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
163f0 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
16400 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
16410 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
16420 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
16430 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
16440 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
16450 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
16460 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
16470 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
16480 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
16490 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
164a0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
164b0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
164c0 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
164d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
164e0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
164f0 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b  _SCAN option tak
16500 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
16510 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ger.** argument 
16520 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
16530 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
16540 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
16550 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a  able or disable.
16560 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  ** the use of co
16570 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
16580 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
16590 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
165a0 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e   optimizer..** ^
165b0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
165c0 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
165d0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
165e0 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
165f0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
16600 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16610 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
16620 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
16630 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
16640 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
16650 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
16660 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
16670 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
16680 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
16690 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
166a0 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
166b0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
166c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
166d0 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
166e0 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
166f0 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
16700 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
16710 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
16720 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
16730 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
16740 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
16750 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
16760 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
16770 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
16780 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
16790 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
167a0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
167b0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
167c0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
167d0 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
167e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
167f0 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
16800 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16810 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
16820 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
16830 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
16840 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
16850 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
16860 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
16870 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
16880 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
16890 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
168a0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
168b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
168c0 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
168d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
168e0 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
168f0 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
16900 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
16910 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
16920 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
16930 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
16940 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
16950 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
16960 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
16970 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
16980 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
16990 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
169a0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
169b0 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
169c0 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
169d0 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
169e0 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
169f0 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
16a00 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
16a10 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
16a20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
16a30 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
16a40 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
16a50 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
16a60 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
16a70 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
16a80 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
16a90 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
16aa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16ab0 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
16ac0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
16ad0 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
16ae0 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
16af0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
16b00 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
16b10 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
16b20 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
16b30 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
16b40 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
16b50 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
16b60 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
16b70 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
16b80 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
16b90 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
16ba0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
16bb0 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
16bc0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
16bd0 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
16be0 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
16bf0 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
16c00 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
16c10 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
16c20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
16c30 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
16c40 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
16c50 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
16c60 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
16c70 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
16c80 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
16c90 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
16ca0 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
16cb0 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
16cc0 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
16cd0 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
16ce0 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
16cf0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16d00 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
16d10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16d20 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
16d30 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
16d40 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
16d50 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
16d60 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
16d70 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
16d80 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
16d90 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
16da0 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
16db0 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
16dc0 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
16dd0 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
16de0 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
16df0 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
16e00 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
16e10 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
16e20 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
16e30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16e40 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
16e50 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
16e60 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
16e70 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
16e80 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
16e90 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
16ea0 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
16eb0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
16ec0 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
16ed0 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79  will be silently
16ee0 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65   truncated if ne
16ef0 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
16f00 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65  it does not exce
16f10 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ed the.** compil
16f20 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
16f30 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
16f40 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
16f50 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
16f60 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
16f70 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
16f80 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
16f90 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
16fa0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
16fb0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
16fc0 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
16fd0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
16fe0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
16ff0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
17000 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
17010 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17020 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
17030 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
17040 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
17050 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e  _HEAPSIZE option
17060 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
17070 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a  le if SQLite is.
17080 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  ** compiled for 
17090 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65  Windows with the
170a0 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
170b0 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
170c0 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65  ssor macro.** de
170d0 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43  fined. ^SQLITE_C
170e0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
170f0 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
17100 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
17110 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
17120 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
17130 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
17140 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
17150 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  p..** </dl>.**.*
17160 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
17170 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d  G_PCACHE_HDRSZ]]
17180 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
17190 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
171a0 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
171b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
171c0 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e  CHE_HDRSZ option
171d0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
171e0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
171f0 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
17200 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
17210 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68  d writes into th
17220 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e  at integer the n
17230 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a  umber of extra.*
17240 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65  * bytes per page
17250 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61   required for ea
17260 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49  ch page in [SQLI
17270 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
17280 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f  CHE]..** The amo
17290 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61  unt of extra spa
172a0 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20  ce required can 
172b0 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67  change depending
172c0 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72   on the compiler
172d0 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74  ,.** target plat
172e0 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65  form, and SQLite
172f0 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20   version..**.** 
17300 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17310 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PMASZ]].** <dt>S
17320 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
17330 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
17340 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
17350 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
17360 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
17370 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
17380 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  n unsigned integ
17390 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20  er and sets the 
173a0 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a  "Minimum PMA Siz
173b0 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69  e" for the multi
173c0 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74  threaded.** sort
173d0 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67  er to that integ
173e0 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  er.  The default
173f0 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a   minimum PMA Siz
17400 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a  e is set by the.
17410 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45  ** [SQLITE_SORTE
17420 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65  R_PMASZ] compile
17430 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e  -time option.  N
17440 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c  ew threads are l
17450 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65  aunched.** to he
17460 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65  lp with sort ope
17470 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c  rations when mul
17480 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69  tithreaded sorti
17490 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64  ng.** is enabled
174a0 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41   (using the [PRA
174b0 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d  GMA threads] com
174c0 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d  mand) and the am
174d0 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a  ount of content.
174e0 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20  ** to be sorted 
174f0 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65  exceeds the page
17500 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20   size times the 
17510 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a  minimum of the.*
17520 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f  * [PRAGMA cache_
17530 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e  size] setting an
17540 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a  d this value..**
17550 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
17560 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17570 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
17580 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
17590 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
175a0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
175b0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
175c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
175d0 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
175e0 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
175f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17600 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
17610 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
17620 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
17630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17640 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
17650 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
17660 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
17670 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17680 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
17690 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
176a0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
176b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
176c0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
176d0 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
176e0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
176f0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
17700 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
17710 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
17720 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
17730 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
17740 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17750 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
17760 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
17770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17780 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
17790 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
177a0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
177b0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
177c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
177d0 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
177e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
177f0 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
17800 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
17810 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
17820 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
17830 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
17840 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17850 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
17860 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
17870 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17880 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
17890 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
178a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
178b0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
178c0 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
178d0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
178e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
178f0 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
17900 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
17910 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17920 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
17930 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
17940 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17950 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
17960 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
17970 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
17980 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
17990 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
179a0 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
179b0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
179c0 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
179d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
179e0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
179f0 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69  EX_SCAN 20  /* i
17a00 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
17a10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
17a20 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20  OG       21  /* 
17a30 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a  xSqllog, void* *
17a40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17a50 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
17a60 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69  E    22  /* sqli
17a70 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74  te3_int64, sqlit
17a80 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66  e3_int64 */.#def
17a90 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17aa0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
17ab0 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74        23  /* int
17ac0 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e   nByte */.#defin
17ad0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17ae0 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20  PCACHE_HDRSZ    
17af0 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a      24  /* int *
17b00 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  psz */.#define S
17b10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
17b20 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  SZ              
17b30 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64   25  /* unsigned
17b40 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f   int szPma */../
17b50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
17b60 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
17b70 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
17b80 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
17b90 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
17ba0 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
17bb0 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
17bc0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
17bd0 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
17be0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
17bf0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
17c00 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
17c10 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
17c20 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
17c30 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
17c40 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
17c50 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
17c60 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
17c70 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
17c80 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
17c90 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
17ca0 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
17cb0 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
17cc0 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
17cd0 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
17ce0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
17cf0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
17d00 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
17d10 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
17d20 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
17d30 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
17d40 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
17d50 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
17d60 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
17d70 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
17d80 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
17d90 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
17da0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
17db0 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
17dc0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
17dd0 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
17de0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
17df0 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
17e00 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
17e10 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
17e20 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
17e30 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
17e40 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
17e50 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
17e60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
17e70 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
17e80 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
17e90 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
17ea0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17eb0 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
17ec0 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
17ed0 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
17ee0 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
17ef0 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
17f00 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
17f10 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
17f20 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17f30 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
17f40 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
17f50 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
17f60 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
17f70 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
17f80 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
17f90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
17fa0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
17fb0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
17fc0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
17fd0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
17fe0 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
17ff0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
18000 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
18010 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
18020 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
18030 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18040 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
18050 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
18060 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
18070 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
18080 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
18090 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
180a0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
180b0 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
180c0 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
180d0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
180e0 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
180f0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
18100 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
18110 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
18120 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
18130 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
18140 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
18150 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
18160 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
18170 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
18180 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
18190 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
181a0 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
181b0 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
181c0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
181d0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
181e0 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
181f0 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
18200 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
18210 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
18220 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
18230 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
18240 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
18250 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
18260 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
18270 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
18280 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
18290 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
182a0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
182b0 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
182c0 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
182d0 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
182e0 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
182f0 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
18300 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
18310 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
18320 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
18330 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
18340 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
18350 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
18360 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
18370 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
18380 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
18390 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
183a0 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
183b0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
183c0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
183d0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
183e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
183f0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
18400 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
18410 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
18420 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
18430 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
18440 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
18450 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
18460 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
18470 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
18480 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
18490 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
184a0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
184b0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
184c0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
184d0 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
184e0 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
184f0 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
18500 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
18510 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18520 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
18530 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
18540 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
18550 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
18560 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
18570 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
18580 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18590 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
185a0 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
185b0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
185c0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
185d0 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
185e0 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
185f0 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
18600 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
18610 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
18620 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
18630 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
18640 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
18650 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
18660 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
18670 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
18680 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
18690 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
186a0 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
186b0 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
186c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
186d0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
186e0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
186f0 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
18700 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
18710 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
18720 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
18730 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
18740 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
18750 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
18760 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18770 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
18780 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
18790 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
187a0 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
187b0 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
187c0 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
187d0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
187e0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
187f0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
18800 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
18810 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
18820 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18830 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20  IG_ENABLE_FKEY  
18840 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20     1002  /* int 
18850 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
18860 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18870 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20  ENABLE_TRIGGER  
18880 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1003  /* int int
18890 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  * */.../*.** CAP
188a0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
188b0 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
188c0 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
188d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
188e0 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
188f0 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
18900 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
18910 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
18920 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
18930 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
18940 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
18950 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
18960 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
18970 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
18980 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
18990 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53  patibility..*/.S
189a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
189b0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
189c0 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
189d0 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
189e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
189f0 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
18a00 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  owid.**.** ^Each
18a10 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53   entry in most S
18a20 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78  QLite tables (ex
18a30 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55  cept for [WITHOU
18a40 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29  T ROWID] tables)
18a50 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65  .** has a unique
18a60 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
18a70 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
18a80 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
18a90 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
18aa0 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
18ab0 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
18ac0 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
18ad0 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
18ae0 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
18af0 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
18b00 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
18b10 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
18b20 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
18b30 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
18b40 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
18b50 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
18b60 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
18b70 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
18b80 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
18b90 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
18ba0 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
18bb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
18bc0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
18bd0 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65  wid(D) interface
18be0 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
18bf0 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20  wid] of the .** 
18c00 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63  most recent succ
18c10 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
18c20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62  into a rowid tab
18c30 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74  le or [virtual t
18c40 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61  able].** on data
18c50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18c60 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69  D..** ^Inserts i
18c70 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  nto [WITHOUT ROW
18c80 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e  ID] tables are n
18c90 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20  ot recorded..** 
18ca0 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
18cb0 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f  l [INSERT]s into
18cc0 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a   rowid tables.**
18cd0 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
18ce0 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62  red on the datab
18cf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
18d00 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  , .** then sqlit
18d10 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
18d20 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20  owid(D) returns 
18d30 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  zero..**.** ^(If
18d40 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
18d50 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
18d60 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61  gger or within a
18d70 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
18d80 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  .** method, then
18d90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
18da0 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72  ll return the [r
18db0 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
18dc0 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20  erted.** row as 
18dd0 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
18de0 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
18df0 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72  able method is r
18e00 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
18e10 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
18e20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
18e30 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68   method ends, th
18e40 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
18e50 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
18e60 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
18e70 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
18e80 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  re the trigger o
18e90 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  r virtual.** tab
18ea0 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e  le method began.
18eb0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
18ec0 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
18ed0 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
18ee0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
18ef0 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
18f00 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
18f10 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
18f20 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
18f30 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
18f40 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
18f50 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
18f60 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
18f70 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
18f80 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
18f90 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
18fa0 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
18fb0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
18fc0 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
18fd0 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
18fe0 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
18ff0 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
19000 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
19010 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
19020 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
19030 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
19040 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
19050 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
19060 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
19070 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
19080 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
19090 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
190a0 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
190b0 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
190c0 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
190d0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
190e0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
190f0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
19100 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
19110 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
19120 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
19130 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
19140 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
19150 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
19160 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
19170 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
19180 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
19190 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
191a0 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
191b0 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
191c0 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
191d0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
191e0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
191f0 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
19200 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
19210 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
19220 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
19230 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
19240 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19250 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
19260 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
19270 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
19280 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
19290 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
192a0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
192b0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
192c0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
192d0 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
192e0 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
192f0 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
19300 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
19310 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
19320 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53  rt [rowid]..*/.S
19330 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
19340 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
19350 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19360 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
19370 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
19380 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
19390 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
193a0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
193b0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
193c0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
193d0 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
193e0 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
193f0 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
19400 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
19410 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
19420 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
19430 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74  ement on the dat
19440 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19450 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
19460 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
19470 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20  ..** ^Executing 
19480 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
19490 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  f SQL statement 
194a0 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20  does not modify 
194b0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
194c0 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
194d0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  nction..**.** ^O
194e0 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
194f0 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65   directly by the
19500 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
19510 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
19520 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ent are.** consi
19530 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72  dered - auxiliar
19540 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
19550 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47   by [CREATE TRIG
19560 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c  GER | triggers],
19570 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65   .** [foreign ke
19580 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52  y actions] or [R
19590 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
195a0 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
195b0 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
195c0 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f  * .** Changes to
195d0 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
195e0 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
195f0 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20  .** [INSTEAD OF 
19600 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41  trigger | INSTEA
19610 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61  D OF triggers] a
19620 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
19630 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72  ^The value .** r
19640 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
19650 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d  e3_changes() imm
19660 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61  ediately after a
19670 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
19680 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73   or .** DELETE s
19690 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20  tatement run on 
196a0 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73  a view is always
196b0 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e   zero. Only chan
196c0 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c  ges made to real
196d0 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20   .** tables are 
196e0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
196f0 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63  hings are more c
19700 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68  omplicated if th
19710 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
19720 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  s() function is.
19730 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c  ** executed whil
19740 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  e a trigger prog
19750 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  ram is running. 
19760 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20  This may happen 
19770 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61  if the.** progra
19780 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e  m uses the [chan
19790 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
197a0 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20  on], or if some 
197b0 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  other callback.*
197c0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b  * function invok
197d0 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  es sqlite3_chang
197e0 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45  es() directly. E
197f0 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a  ssentially:.** .
19800 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
19810 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72  > ^(Before enter
19820 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72  ing a trigger pr
19830 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20  ogram the value 
19840 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
19850 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68        sqlite3_ch
19860 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
19870 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72   is saved. After
19880 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
19890 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  gram .**        
198a0 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68  has finished, th
198b0 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65  e original value
198c0 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a   is restored.)^.
198d0 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ** .**   <li> ^(
198e0 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  Within a trigger
198f0 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e   program each IN
19900 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64  SERT, UPDATE and
19910 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20   DELETE .**     
19920 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74     statement set
19930 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  s the value retu
19940 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
19950 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
19960 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65       upon comple
19970 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20  tion as normal. 
19980 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20  Of course, this 
19990 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69  value will not i
199a0 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20  nclude .**      
199b0 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65    any changes pe
199c0 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74  rformed by sub-t
199d0 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20  riggers, as the 
199e0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
199f0 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c  ) .**        val
19a00 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64  ue will be saved
19a10 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66   and restored af
19a20 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69  ter each sub-tri
19a30 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a  gger has run.)^.
19a40 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
19a50 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74  ^This means that
19a60 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28   if the changes(
19a70 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28  ) SQL function (
19a80 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75  or similar) is u
19a90 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  sed.** by the fi
19aa0 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  rst INSERT, UPDA
19ab0 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
19ac0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
19ad0 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20  trigger, it .** 
19ae0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
19af0 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68  e as set when th
19b00 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d  e calling statem
19b10 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74  ent began execut
19b20 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  ing..** ^If it i
19b30 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65  s used by the se
19b40 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65  cond or subseque
19b50 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e  nt such statemen
19b60 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
19b70 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20  er .** program, 
19b80 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
19b90 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20  ed reflects the 
19ba0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
19bb0 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  odified by the .
19bc0 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45  ** previous INSE
19bd0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
19be0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
19bf0 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
19c00 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  rigger..**.** Se
19c10 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
19c20 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
19c30 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
19c40 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
19c50 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
19c60 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
19c70 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
19c80 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
19c90 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
19ca0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
19cb0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
19cc0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
19cd0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
19ce0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
19cf0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
19d00 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
19d10 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
19d20 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
19d30 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
19d40 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
19d50 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
19d60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19d70 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
19d80 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
19d90 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
19da0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  on returns the t
19db0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72  otal number of r
19dc0 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f  ows inserted, mo
19dd0 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  dified or.** del
19de0 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53  eted by all [INS
19df0 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f  ERT], [UPDATE] o
19e00 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
19e10 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a  ments completed.
19e20 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  ** since the dat
19e30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19e40 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63   was opened, inc
19e50 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65  luding those exe
19e60 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  cuted as.** part
19e70 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67   of trigger prog
19e80 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67  rams. ^Executing
19e90 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
19ea0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
19eb0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66  .** does not aff
19ec0 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  ect the value re
19ed0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
19ee0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
19ef0 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67  )..** .** ^Chang
19f00 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  es made as part 
19f10 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  of [foreign key 
19f20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63  actions] are inc
19f30 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  luded in the.** 
19f40 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65  count, but those
19f50 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
19f60 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
19f70 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
19f80 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e  re.** not. ^Chan
19f90 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
19fa0 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
19fb0 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46  ed by INSTEAD OF
19fc0 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72   triggers .** ar
19fd0 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
19fe0 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  * .** See also t
19ff0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
1a000 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1a010 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
1a020 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
1a030 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
1a040 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1a050 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
1a060 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
1a070 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
1a080 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
1a090 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a0a0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
1a0b0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1a0c0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
1a0d0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
1a0e0 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
1a0f0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1a100 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
1a110 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1a120 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
1a130 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
1a140 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a150 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
1a160 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
1a170 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ry.**.** ^This f
1a180 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
1a190 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
1a1a0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
1a1b0 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
1a1c0 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
1a1d0 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
1a1e0 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
1a1f0 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
1a200 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
1a210 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
1a220 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
1a230 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
1a240 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
1a250 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
1a260 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
1a270 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
1a280 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
1a290 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
1a2a0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
1a2b0 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
1a2c0 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
1a2d0 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
1a2e0 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
1a2f0 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
1a300 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
1a310 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
1a320 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
1a330 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1a340 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
1a350 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
1a360 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
1a370 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
1a380 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
1a390 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
1a3a0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
1a3b0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
1a3c0 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
1a3d0 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
1a3e0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
1a3f0 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
1a400 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
1a410 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
1a420 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
1a430 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
1a440 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
1a450 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
1a460 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
1a470 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
1a480 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
1a490 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
1a4a0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
1a4b0 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
1a4c0 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
1a4d0 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
1a4e0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
1a4f0 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
1a500 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
1a510 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
1a520 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
1a530 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
1a540 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
1a550 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
1a560 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1a570 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
1a580 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
1a590 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
1a5a0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
1a5b0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1a5c0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
1a5d0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
1a5e0 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
1a5f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1a600 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1a610 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1a620 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1a630 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
1a640 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
1a650 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
1a660 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
1a670 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
1a680 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
1a690 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
1a6a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1a6b0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
1a6c0 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
1a6d0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1a6e0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1a6f0 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
1a700 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
1a710 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
1a720 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
1a730 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1a740 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
1a750 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
1a760 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
1a770 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
1a780 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
1a790 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1a7a0 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
1a7b0 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
1a7c0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
1a7d0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1a7e0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1a7f0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1a800 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
1a810 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
1a820 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a830 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
1a840 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1a850 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
1a860 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
1a870 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
1a880 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  appen..*/.SQLITE
1a890 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
1a8a0 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
1a8b0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1a8c0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
1a8d0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
1a8e0 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
1a8f0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
1a900 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
1a910 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
1a920 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
1a930 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
1a940 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
1a950 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
1a960 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
1a970 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
1a980 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
1a990 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
1a9a0 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
1a9b0 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
1a9c0 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
1a9d0 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
1a9e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1a9f0 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
1aa00 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
1aa10 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
1aa20 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
1aa30 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
1aa40 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
1aa50 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
1aa60 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
1aa70 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
1aa80 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
1aa90 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
1aaa0 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
1aab0 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
1aac0 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
1aad0 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
1aae0 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
1aaf0 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
1ab00 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
1ab10 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
1ab20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
1ab30 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
1ab40 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
1ab50 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
1ab60 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
1ab70 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
1ab80 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
1ab90 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
1aba0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
1abb0 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
1abc0 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
1abd0 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
1abe0 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
1abf0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1ac00 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1ac10 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
1ac20 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
1ac30 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
1ac40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
1ac50 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
1ac60 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
1ac70 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
1ac80 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
1ac90 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
1aca0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
1acb0 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
1acc0 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
1acd0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
1ace0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
1acf0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
1ad00 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
1ad10 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
1ad20 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
1ad30 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
1ad40 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1ad50 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
1ad60 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
1ad70 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
1ad80 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
1ad90 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1ada0 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
1adb0 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
1adc0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
1add0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
1ade0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1adf0 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
1ae00 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
1ae10 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
1ae20 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
1ae30 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
1ae40 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
1ae50 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
1ae60 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
1ae70 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
1ae80 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
1ae90 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
1aea0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
1aeb0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
1aec0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
1aed0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1aee0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
1aef0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
1af00 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1af10 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
1af20 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
1af30 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ql);.SQLITE_API 
1af40 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
1af50 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
1af60 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
1af70 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
1af80 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
1af90 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
1afa0 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45  USY Errors.** KE
1afb0 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61  YWORDS: {busy-ha
1afc0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20  ndler callback} 
1afd0 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a  {busy handler}.*
1afe0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1aff0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
1b000 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65  ,X,P) routine se
1b010 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
1b020 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74  nction X.** that
1b030 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
1b040 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
1b050 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  P whenever.** an
1b060 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
1b070 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74   to access a dat
1b080 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f  abase table asso
1b090 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b  ciated with.** [
1b0a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b0b0 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74  ion] D when anot
1b0c0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
1b0d0 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65   process has the
1b0e0 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a   table locked..*
1b0f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75  * The sqlite3_bu
1b100 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74  sy_handler() int
1b110 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
1b120 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b  o implement.** [
1b130 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1b140 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41  eout()] and [PRA
1b150 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1b160 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
1b170 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
1b180 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
1b190 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73  LITE_BUSY].** is
1b1a0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1b1b0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
1b1c0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
1b1d0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
1b1e0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
1b1f0 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
1b200 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
1b210 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
1b220 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
1b230 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1b240 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1b250 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1b260 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
1b270 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
1b280 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
1b290 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
1b2a0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1b2b0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
1b2c0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
1b2d0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1b2e0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
1b2f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
1b300 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
1b310 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
1b320 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72   been invoked pr
1b330 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65  eviously for the
1b340 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76   same locking ev
1b350 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
1b360 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
1b370 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
1b380 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
1b390 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
1b3a0 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
1b3b0 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
1b3c0 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65  LITE_BUSY] is re
1b3d0 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65  turned.** to the
1b3e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a   application..**
1b3f0 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
1b400 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1b410 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
1b420 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
1b430 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68  ade to access th
1b440 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  e database and t
1b450 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
1b460 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
1b470 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
1b480 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
1b490 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
1b4a0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
1b4b0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
1b4c0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
1b4d0 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
1b4e0 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
1b4f0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
1b500 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
1b510 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
1b520 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
1b530 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
1b540 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
1b550 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  ].** to the appl
1b560 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20  ication instead 
1b570 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
1b580 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1b590 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
1b5a0 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
1b5b0 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
1b5c0 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
1b5d0 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
1b5e0 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
1b5f0 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
1b600 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
1b610 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
1b620 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
1b630 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
1b640 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
1b650 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
1b660 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
1b670 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1b680 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
1b690 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
1b6a0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
1b6b0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
1b6c0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
1b6d0 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
1b6e0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1b6f0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
1b700 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
1b710 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
1b720 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1b730 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
1b740 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
1b750 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
1b760 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
1b770 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
1b780 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
1b790 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
1b7a0 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
1b7b0 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
1b7c0 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
1b7d0 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
1b7e0 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
1b7f0 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1b800 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
1b810 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1b820 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
1b830 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s NULL..**.** ^(
1b840 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1b850 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1b860 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
1b870 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
1b880 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b890 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
1b8a0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
1b8b0 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
1b8c0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
1b8d0 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
1b8e0 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
1b8f0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1b900 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61  ()].** or evalua
1b910 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73  ting [PRAGMA bus
1b920 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c  y_timeout=N] wil
1b930 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  l change the.** 
1b940 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64  busy handler and
1b950 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20   thus clear any 
1b960 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62  previously set b
1b970 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
1b980 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
1b990 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
1b9a0 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
1b9b0 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
1b9c0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
1b9d0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1b9e0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1b9f0 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65  andler.  In othe
1ba00 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20  r words,.** the 
1ba10 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1ba20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20  not reentrant.  
1ba30 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
1ba40 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
1ba50 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
1ba60 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
1ba70 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
1ba80 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
1ba90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1baa0 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
1bab0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
1bac0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1bad0 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49  handler..*/.SQLI
1bae0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1baf0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1bb00 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
1bb10 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
1bb20 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1bb30 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
1bb40 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e   Timeout.**.** ^
1bb50 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
1bb60 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
1bb70 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
1bb80 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
1bb90 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
1bba0 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
1bbb0 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
1bbc0 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
1bbd0 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
1bbe0 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
1bbf0 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
1bc00 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1bc10 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1bc20 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
1bc30 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
1bc40 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
1bc50 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1bc60 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
1bc70 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
1bc80 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
1bc90 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
1bca0 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
1bcb0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
1bcc0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
1bcd0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1bce0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
1bcf0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
1bd00 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
1bd10 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
1bd20 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
1bd30 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1bd40 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1bd50 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
1bd60 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1bd70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bd80 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d  ] at any given m
1bd90 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
1bda0 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
1bdb0 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
1bdc0 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
1bdd0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
1bde0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
1bdf0 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
1be00 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
1be10 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
1be20 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  eared.)^.**.** S
1be30 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d  ee also:  [PRAGM
1be40 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a  A busy_timeout].
1be50 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1be60 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
1be70 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
1be80 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
1be90 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
1bea0 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
1beb0 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
1bec0 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ies.**.** This i
1bed0 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
1bee0 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
1bef0 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
1bf00 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1bf10 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
1bf20 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1bf30 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
1bf40 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
1bf50 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
1bf60 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
1bf70 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
1bf80 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
1bf90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1bfa0 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
1bfb0 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
1bfc0 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
1bfd0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
1bfe0 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
1bff0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
1c000 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
1c010 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
1c020 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
1c030 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
1c040 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
1c050 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
1c060 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
1c070 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
1c080 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
1c090 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
1c0a0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
1c0b0 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
1c0c0 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
1c0d0 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
1c0e0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
1c0f0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1c100 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
1c110 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
1c120 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1c130 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
1c140 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
1c150 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
1c160 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
1c170 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
1c180 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
1c190 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1c1a0 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
1c1b0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
1c1c0 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
1c1d0 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
1c1e0 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
1c1f0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
1c200 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
1c210 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
1c220 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
1c230 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
1c240 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
1c250 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1c260 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
1c270 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
1c280 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
1c290 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
1c2a0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1c2b0 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
1c2c0 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
1c2d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1c2e0 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
1c2f0 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
1c300 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
1c310 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
1c320 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
1c330 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
1c340 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
1c350 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1c360 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1c370 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
1c380 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
1c390 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
1c3a0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
1c3b0 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
1c3c0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1c3d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1c3e0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
1c3f0 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
1c400 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
1c410 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1c420 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
1c430 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
1c440 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
1c450 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
1c460 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
1c470 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
1c480 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1c490 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
1c4a0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
1c4b0 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
1c4c0 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
1c4d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
1c4e0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
1c4f0 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
1c500 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
1c510 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
1c520 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
1c530 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
1c540 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
1c550 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
1c560 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1c570 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1c580 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
1c590 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1c5a0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
1c5b0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1c5c0 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
1c5d0 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
1c5e0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
1c5f0 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
1c600 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1c610 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
1c620 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1c630 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
1c640 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1c650 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
1c660 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1c670 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
1c680 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
1c690 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1c6a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c6b0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
1c6c0 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
1c6d0 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
1c6e0 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
1c6f0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1c700 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
1c710 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
1c720 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
1c730 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1c740 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1c750 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1c760 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1c770 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1c780 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1c790 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1c7a0 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1c7b0 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1c7c0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1c7d0 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1c7e0 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1c7f0 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1c800 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1c810 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1c820 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1c830 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1c840 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1c850 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1c860 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1c870 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1c880 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1c890 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1c8a0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1c8b0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1c8c0 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1c8d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1c8e0 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1c8f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1c900 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1c910 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1c920 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1c930 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1c940 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1c950 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1c960 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1c970 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1c980 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1c990 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1c9a0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1c9b0 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1c9c0 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1c9d0 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1c9e0 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1c9f0 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1ca00 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1ca10 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1ca20 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1ca30 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1ca40 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1ca50 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1ca60 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1ca70 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1ca80 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1ca90 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1caa0 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1cab0 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1cac0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1cad0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1cae0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1caf0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  rrmsg()]..*/.SQL
1cb00 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1cb10 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1cb20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1cb30 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1cb40 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1cb50 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1cb60 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1cb70 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1cb80 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1cb90 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1cba0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1cbb0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1cbc0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1cbd0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1cbe0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1cbf0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1cc00 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1cc10 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1cc20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1cc30 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1cc40 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1cc50 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1cc60 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1cc70 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1cc80 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1cc90 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
1cca0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1ccb0 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
1ccc0 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
1ccd0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1cce0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1ccf0 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
1cd00 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
1cd10 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
1cd20 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
1cd30 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1cd40 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
1cd50 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
1cd60 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
1cd70 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
1cd80 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
1cd90 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
1cda0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
1cdb0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1cdc0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
1cdd0 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1cde0 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
1cdf0 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
1ce00 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
1ce10 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
1ce20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
1ce30 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
1ce40 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
1ce50 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
1ce60 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1ce70 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
1ce80 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1ce90 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
1cea0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1ceb0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1cec0 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
1ced0 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
1cee0 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
1cef0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1cf00 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
1cf10 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
1cf20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
1cf30 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
1cf40 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
1cf50 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
1cf60 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
1cf70 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
1cf80 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
1cf90 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
1cfa0 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
1cfb0 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
1cfc0 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
1cfd0 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
1cfe0 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
1cff0 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
1d000 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
1d010 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
1d020 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1d030 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
1d040 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
1d050 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
1d060 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1d070 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
1d080 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
1d090 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
1d0a0 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
1d0b0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
1d0c0 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
1d0d0 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
1d0e0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
1d0f0 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
1d100 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
1d110 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
1d120 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
1d130 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
1d140 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
1d150 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1d160 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
1d170 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
1d180 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
1d190 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
1d1a0 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
1d1b0 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
1d1c0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1d1d0 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
1d1e0 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
1d1f0 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
1d200 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
1d210 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
1d220 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
1d230 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
1d240 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
1d250 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
1d260 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
1d270 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
1d280 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
1d290 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
1d2a0 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
1d2b0 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
1d2c0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
1d2d0 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
1d2e0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1d2f0 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
1d300 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1d310 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  rintf()..**.** T
1d320 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
1d330 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
1d340 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
1d350 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
1d360 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
1d370 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
1d380 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
1d390 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
1d3a0 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
1d3b0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1d3c0 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
1d3d0 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
1d3e0 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
1d3f0 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
1d400 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
1d410 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
1d420 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
1d430 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
1d440 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
1d450 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
1d460 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
1d470 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
1d480 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
1d490 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
1d4a0 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
1d4b0 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
1d4c0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1d4d0 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
1d4e0 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
1d4f0 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
1d500 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
1d510 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
1d520 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
1d530 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
1d540 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
1d550 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
1d560 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
1d570 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
1d580 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
1d590 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1d5a0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1d5b0 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
1d5c0 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
1d5d0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1d5e0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
1d5f0 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
1d600 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
1d610 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
1d620 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1d630 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1d640 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1d650 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1d660 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1d670 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
1d680 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1d690 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1d6a0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1d6b0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1d6c0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1d6d0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1d6e0 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
1d6f0 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
1d700 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
1d710 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
1d720 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
1d730 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
1d740 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
1d750 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1d760 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1d770 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1d780 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
1d790 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1d7a0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1d7b0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1d7c0 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
1d7d0 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
1d7e0 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
1d7f0 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
1d800 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
1d810 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
1d820 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1d830 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1d840 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1d850 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
1d860 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
1d870 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1d880 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
1d890 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
1d8a0 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
1d8b0 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
1d8c0 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
1d8d0 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
1d8e0 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
1d8f0 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
1d900 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
1d910 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
1d920 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
1d930 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
1d940 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
1d950 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
1d960 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
1d970 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1d980 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
1d990 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
1d9a0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
1d9b0 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
1d9c0 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
1d9d0 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
1d9e0 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
1d9f0 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
1da00 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
1da10 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
1da20 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
1da30 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
1da40 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1da50 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1da60 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1da70 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1da80 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
1da90 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1daa0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1dab0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1dac0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1dad0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1dae0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1daf0 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
1db00 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
1db10 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
1db20 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
1db30 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
1db40 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
1db50 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
1db60 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1db70 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
1db80 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
1db90 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
1dba0 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
1dbb0 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
1dbc0 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
1dbd0 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
1dbe0 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
1dbf0 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
1dc00 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
1dc10 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
1dc20 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53  t string.)^.*/.S
1dc30 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1dc40 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1dc50 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
1dc60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1dc70 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
1dc80 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1dc90 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54   va_list);.SQLIT
1dca0 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1dcb0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
1dcc0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1dcd0 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  r*, ...);.SQLITE
1dce0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1dcf0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1dd00 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1dd10 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1dd20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1dd30 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1dd40 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1dd50 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1dd60 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1dd70 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1dd80 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1dd90 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1dda0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1ddb0 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1ddc0 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1ddd0 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1dde0 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1ddf0 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1de00 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1de10 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1de20 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1de30 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1de40 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1de50 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1de60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1de70 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1de80 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1de90 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1dea0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1deb0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1dec0 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1ded0 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1dee0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1def0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1df00 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1df10 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1df20 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1df30 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1df40 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1df50 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1df60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1df70 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1df80 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1df90 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1dfa0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1dfb0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
1dfc0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1dfd0 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  (N) routine work
1dfe0 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73  s just like.** s
1dff0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1e000 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1e010 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34  s an unsigned 64
1e020 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73  -bit integer ins
1e030 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67  tead.** of a sig
1e040 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67  ned 32-bit integ
1e050 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1e060 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1e070 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1e080 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1e090 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1e0a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1e0b0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1e0c0 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1e0d0 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1e0e0 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1e0f0 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1e100 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1e110 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1e120 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1e130 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1e140 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1e150 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1e160 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1e170 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1e180 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1e190 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1e1a0 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1e1b0 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1e1c0 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1e1d0 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1e1e0 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1e1f0 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1e200 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1e210 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1e220 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1e230 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1e240 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1e250 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1e260 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1e270 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1e280 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1e290 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1e2a0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1e2b0 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1e2c0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1e2d0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1e2e0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1e2f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e300 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e  _realloc(X,N) in
1e310 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1e320 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1e330 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1e340 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  ocation X to be 
1e350 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1e360 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70  ..** ^If the X p
1e370 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1e380 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1e390 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1e3a0 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1e3b0 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1e3c0 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1e3d0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1e3e0 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  c(N)..** ^If the
1e3f0 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
1e400 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e410 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  X,N) is zero or.
1e420 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1e430 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1e440 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1e450 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1e460 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e  sqlite3_free(X).
1e470 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1e480 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1e490 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1e4a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1e4b0 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1e4c0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1e4d0 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73  e or NULL if ins
1e4e0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1e4f0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
1e500 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1e510 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1e520 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1e530 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1e540 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1e550 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1e560 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1e570 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1e580 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1e590 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1e5a0 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20  oc(X,N) and the 
1e5b0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1e5c0 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1e5d0 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1e5e0 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e  c(X,N) returns N
1e5f0 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73  ULL and N is pos
1e600 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a  itive, then the.
1e610 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  ** prior allocat
1e620 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64  ion is not freed
1e630 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1e640 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58  ite3_realloc64(X
1e650 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77  ,N) interfaces w
1e660 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73  orks the same as
1e670 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
1e680 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20  loc(X,N) except 
1e690 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62  that N is a 64-b
1e6a0 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
1e6b0 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1e6c0 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65  f a 32-bit signe
1e6d0 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
1e6e0 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f   ^If X is a memo
1e6f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72  ry allocation pr
1e700 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
1e710 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1e720 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1e730 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1e740 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e750 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ), or sqlite3_re
1e760 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a  alloc64(), then.
1e770 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1e780 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (X) returns the 
1e790 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d  size of that mem
1e7a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ory allocation i
1e7b0 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65  n bytes..** ^The
1e7c0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1e7d0 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  by sqlite3_msize
1e7e0 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72  (X) might be lar
1e7f0 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ger than the num
1e800 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
1e810 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58  requested when X
1e820 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20   was allocated. 
1e830 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c   ^If X is a NULL
1e840 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
1e850 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1e860 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20  ) returns zero. 
1e870 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20   If X points to 
1e880 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69  something that i
1e890 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67  s not.** the beg
1e8a0 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79  inning of memory
1e8b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20   allocation, or 
1e8c0 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20  if it points to 
1e8d0 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61  a formerly.** va
1e8e0 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  lid memory alloc
1e8f0 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e  ation that has n
1e900 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74  ow been freed, t
1e910 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1e920 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  .** of sqlite3_m
1e930 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66  size(X) is undef
1e940 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c  ined and possibl
1e950 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
1e960 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1e970 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1e980 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74  _malloc(), sqlit
1e990 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  e3_realloc(),.**
1e9a0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1e9b0 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  4(), and sqlite3
1e9c0 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20  _realloc64().** 
1e9d0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1e9e0 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1e9f0 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1ea00 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1ea10 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1ea20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1ea30 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1ea40 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1ea50 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1ea60 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1ea70 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1ea80 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1ea90 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1eaa0 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1eab0 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1eac0 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1ead0 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1eae0 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1eaf0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1eb00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1eb10 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1eb20 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1eb30 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1eb40 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1eb50 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1eb60 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1eb70 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
1eb80 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1eb90 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
1eba0 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1ebb0 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
1ebc0 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
1ebd0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1ebe0 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1ebf0 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1ec00 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1ec10 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1ec20 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1ec30 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1ec40 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1ec50 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1ec60 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1ec70 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1ec80 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1ec90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1eca0 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
1ecb0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
1ecc0 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
1ecd0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
1ece0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
1ecf0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
1ed00 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
1ed10 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
1ed20 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
1ed30 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
1ed40 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
1ed50 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1ed60 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
1ed70 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
1ed80 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
1ed90 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
1eda0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
1edb0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1edc0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1edd0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
1ede0 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
1edf0 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
1ee00 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1ee10 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
1ee20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
1ee30 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
1ee40 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
1ee50 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
1ee60 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
1ee70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
1ee80 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1ee90 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  oc()]..*/.SQLITE
1eea0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
1eeb0 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
1eec0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1eed0 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36  *sqlite3_malloc6
1eee0 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  4(sqlite3_uint64
1eef0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1ef00 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1ef10 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1ef20 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1ef30 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1ef40 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74  c64(void*, sqlit
1ef50 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49  e3_uint64);.SQLI
1ef60 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
1ef70 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
1ef80 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
1ef90 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  te3_uint64 sqlit
1efa0 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b  e3_msize(void*);
1efb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1efc0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1efd0 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
1efe0 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
1eff0 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
1f000 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
1f010 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
1f020 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
1f030 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f040 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
1f050 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1f060 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1f070 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
1f080 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
1f090 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1f0a0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
1f0b0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
1f0c0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1f0d0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1f0e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1f0f0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
1f100 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
1f110 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
1f120 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
1f130 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
1f140 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1f150 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
1f160 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
1f170 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
1f180 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1f190 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
1f1a0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1f1b0 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
1f1c0 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
1f1d0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1f1e0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1f1f0 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
1f200 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1f210 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
1f220 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
1f230 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
1f240 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
1f250 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
1f260 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
1f270 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
1f280 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
1f290 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
1f2a0 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
1f2b0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
1f2c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f2d0 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
1f2e0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
1f2f0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
1f300 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
1f310 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
1f320 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1f330 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
1f340 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
1f350 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
1f360 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1f370 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
1f380 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
1f390 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
1f3a0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1f3b0 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
1f3c0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1f3d0 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
1f3e0 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c  he reset..*/.SQL
1f3f0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
1f400 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1f410 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
1f420 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
1f430 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1f440 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1f450 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
1f460 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f470 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
1f480 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
1f490 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
1f4a0 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
1f4b0 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
1f4c0 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
1f4d0 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
1f4e0 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
1f4f0 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
1f500 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
1f510 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
1f520 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
1f530 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
1f540 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
1f550 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
1f560 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
1f570 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
1f580 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
1f590 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
1f5a0 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
1f5b0 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
1f5c0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
1f5d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
1f5e0 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
1f5f0 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
1f600 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
1f610 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
1f620 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
1f630 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
1f640 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
1f650 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61   P..** ^The P pa
1f660 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61  rameter can be a
1f670 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1f680 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f  *.** ^If this ro
1f690 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65  utine has not be
1f6a0 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61  en previously ca
1f6b0 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70  lled or if the p
1f6c0 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20  revious.** call 
1f6d0 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20  had N less than 
1f6e0 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  one or a NULL po
1f6f0 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65  inter for P, the
1f700 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a  n the PRNG is.**
1f710 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
1f720 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
1f730 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  d from the xRand
1f740 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
1f750 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
1f760 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1f770 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ject..** ^If the
1f780 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
1f790 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  o this routine h
1f7a0 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20  ad an N of 1 or 
1f7b0 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f  more and a.** no
1f7c0 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68  n-NULL P then th
1f7d0 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
1f7e0 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
1f7f0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
1f800 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
1f810 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
1f820 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
1f830 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
1f840 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1f850 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
1f860 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
1f870 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
1f880 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
1f890 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
1f8a0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
1f8b0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1f8c0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
1f8d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f8e0 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
1f8f0 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1f900 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
1f910 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
1f920 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
1f930 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1f940 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1f950 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
1f960 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
1f970 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
1f980 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f990 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1f9a0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
1f9b0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
1f9c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f9d0 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
1f9e0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1f9f0 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
1fa00 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
1fa10 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
1fa20 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
1fa30 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
1fa40 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
1fa50 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
1fa60 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
1fa70 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1fa80 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
1fa90 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
1faa0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
1fab0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1fac0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
1fad0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
1fae0 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
1faf0 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
1fb00 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
1fb10 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
1fb20 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
1fb30 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
1fb40 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
1fb50 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
1fb60 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
1fb70 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
1fb80 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
1fb90 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1fba0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
1fbb0 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
1fbc0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1fbd0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1fbe0 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
1fbf0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1fc00 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
1fc10 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
1fc20 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
1fc30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
1fc40 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1fc50 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1fc60 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
1fc70 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
1fc80 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1fc90 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
1fca0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
1fcb0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1fcc0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
1fcd0 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
1fce0 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
1fcf0 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
1fd00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1fd10 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
1fd20 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
1fd30 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1fd40 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1fd50 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1fd60 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
1fd70 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1fd80 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1fd90 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
1fda0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
1fdb0 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
1fdc0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
1fdd0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1fde0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1fdf0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
1fe00 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
1fe10 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
1fe20 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1fe30 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
1fe40 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
1fe50 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
1fe60 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1fe70 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
1fe80 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
1fe90 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
1fea0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
1feb0 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
1fec0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
1fed0 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
1fee0 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
1fef0 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
1ff00 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
1ff10 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1ff20 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
1ff30 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
1ff40 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
1ff50 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1ff60 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
1ff70 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1ff80 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
1ff90 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
1ffa0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1ffb0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1ffc0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
1ffd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1ffe0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
1fff0 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
20000 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
20010 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
20020 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
20030 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
20040 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
20050 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
20060 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
20070 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
20080 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
20090 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
200a0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
200b0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
200c0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
200d0 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
200e0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
200f0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
20100 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
20110 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
20120 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
20130 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
20140 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
20150 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
20160 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
20170 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
20180 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
20190 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
201a0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
201b0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
201c0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
201d0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
201e0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
201f0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
20200 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
20210 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
20220 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
20230 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
20240 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
20250 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
20260 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
20270 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
20280 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
20290 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
202a0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
202b0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
202c0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
202d0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
202e0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
202f0 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
20300 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
20310 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
20320 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
20330 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
20340 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
20350 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
20360 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
20370 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
20380 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
20390 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
203a0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
203b0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
203c0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
203d0 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
203e0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
203f0 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
20400 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
20410 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
20420 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
20430 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
20440 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
20450 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
20460 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
20470 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
20480 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
20490 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
204a0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
204b0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
204c0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
204d0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
204e0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
204f0 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
20500 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
20510 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
20520 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
20530 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
20540 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
20550 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
20560 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
20570 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
20580 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
20590 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
205a0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
205b0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
205c0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
205d0 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
205e0 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
205f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
20600 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
20610 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
20620 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
20630 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
20640 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
20650 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20660 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
20670 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
20680 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
20690 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
206a0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
206b0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
206c0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
206d0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
206e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
206f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
20700 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
20710 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
20720 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
20730 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
20740 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
20750 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
20760 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
20770 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
20780 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
20790 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
207a0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
207b0 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
207c0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
207d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
207e0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
207f0 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
20800 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
20810 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
20820 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
20830 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
20840 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
20850 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
20860 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
20870 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
20880 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
20890 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
208a0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
208b0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
208c0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
208d0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
208e0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
208f0 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
20900 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
20910 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
20920 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20930 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
20940 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
20950 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
20960 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
20970 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
20980 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
20990 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
209a0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
209b0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
209c0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
209d0 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
209e0 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
209f0 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
20a00 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
20a10 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
20a20 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
20a30 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
20a40 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
20a50 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
20a60 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
20a70 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
20a80 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
20a90 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
20aa0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
20ab0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
20ac0 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
20ad0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
20ae0 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
20af0 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
20b00 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
20b10 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
20b20 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
20b30 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
20b40 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
20b50 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
20b60 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
20b70 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
20b80 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
20b90 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
20ba0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
20bb0 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
20bc0 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
20bd0 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72  as a [conflict r
20be0 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a  esolution mode].
20bf0 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ** returned from
20c00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
20c10 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
20c20 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
20c30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
20c40 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
20c50 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
20c60 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
20c70 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
20c80 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
20c90 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
20ca0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
20cb0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
20cc0 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
20cd0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
20ce0 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
20cf0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
20d00 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
20d10 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
20d20 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
20d30 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
20d40 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
20d50 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
20d60 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
20d70 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
20d80 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
20d90 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
20da0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
20db0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
20dc0 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
20dd0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
20de0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
20df0 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
20e00 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
20e10 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
20e20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
20e30 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
20e40 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
20e50 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
20e60 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
20e70 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
20e80 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
20e90 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
20ea0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
20eb0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
20ec0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
20ed0 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
20ee0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
20ef0 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
20f00 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
20f10 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
20f20 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
20f30 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
20f40 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
20f50 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
20f60 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
20f70 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
20f80 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
20f90 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
20fa0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
20fb0 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
20fc0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
20fd0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20fe0 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
20ff0 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
21000 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
21010 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
21020 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
21030 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
21040 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
21050 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
21060 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
21070 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
21080 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
21090 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
210a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
210b0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
210c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
210d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
210e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
210f0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
21100 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
21110 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
21120 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21130 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21140 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
21150 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21160 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21170 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21180 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
21190 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
211a0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
211b0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
211c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
211d0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
211e0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
211f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21200 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21210 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21220 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
21230 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
21240 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
21250 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21260 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21270 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
21280 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
21290 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
212a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
212b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
212c0 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
212d0 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
212e0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
212f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21300 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21310 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
21320 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
21330 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
21340 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21350 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21360 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
21370 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
21380 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
21390 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
213a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
213b0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
213c0 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
213d0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
213e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
213f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21400 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
21410 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
21420 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
21430 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21440 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21450 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
21460 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
21470 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
21480 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
21490 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
214a0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
214b0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
214c0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
214d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
214e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
214f0 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
21500 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
21510 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
21520 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21530 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21540 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
21550 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
21560 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
21570 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21580 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21590 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
215a0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
215b0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
215c0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
215d0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
215e0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
215f0 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
21600 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21610 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21620 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
21630 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
21640 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21650 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21660 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21670 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
21680 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
21690 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
216a0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
216b0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
216c0 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
216d0 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
216e0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
216f0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
21700 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21710 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
21720 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
21730 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
21740 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21750 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21760 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
21770 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
21780 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
21790 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
217a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
217b0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
217c0 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
217d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
217e0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
217f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21800 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
21810 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
21820 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
21830 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21840 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21850 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
21860 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
21870 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
21880 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21890 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
218a0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
218b0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
218c0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
218d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
218e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
218f0 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
21900 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
21910 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
21920 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21930 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
21940 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
21950 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
21960 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
21970 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21980 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
21990 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
219a0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
219b0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
219c0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
219d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
219e0 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
219f0 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
21a00 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
21a10 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
21a20 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
21a30 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
21a40 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
21a50 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
21a60 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
21a70 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
21a80 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
21a90 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
21aa0 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
21ab0 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
21ac0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
21ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21ae0 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
21af0 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
21b00 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56   SQLITE_RECURSIV
21b10 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20  E            33 
21b20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
21b30 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21b40 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43       */../*.** C
21b50 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
21b60 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
21b70 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
21b80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
21b90 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
21ba0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
21bb0 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
21bc0 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
21bd0 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
21be0 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
21bf0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
21c00 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
21c10 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
21c20 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
21c30 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
21c40 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
21c50 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
21c60 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
21c70 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
21c80 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
21c90 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
21ca0 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
21cb0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
21cc0 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
21cd0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
21ce0 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
21cf0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
21d00 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
21d10 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
21d20 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
21d30 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
21d40 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
21d50 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
21d60 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
21d70 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
21d80 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
21d90 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
21da0 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
21db0 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
21dc0 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
21dd0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
21de0 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
21df0 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
21e00 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
21e10 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20  sed to limit.** 
21e20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62  the length of [b
21e30 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20  ound parameter] 
21e40 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65  expansion in the
21e50 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74   output of sqlit
21e60 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a  e3_trace()..**.*
21e70 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
21e80 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
21e90 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
21ea0 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
21eb0 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
21ec0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
21ed0 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
21ee0 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
21ef0 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
21f00 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
21f10 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
21f20 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
21f30 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
21f40 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
21f50 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
21f60 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
21f70 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
21f80 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
21f90 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
21fa0 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
21fb0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
21fc0 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
21fd0 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
21fe0 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
21ff0 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
22000 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
22010 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
22020 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
22030 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
22040 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
22050 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
22060 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
22070 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
22080 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
22090 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
220a0 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
220b0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
220c0 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
220d0 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
220e0 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
220f0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
22100 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te..*/.SQLITE_AP
22110 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
22120 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
22130 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
22140 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
22150 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
22160 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45  _API SQLITE_EXPE
22170 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
22180 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
22190 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
221a0 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
221b0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
221c0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
221d0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
221e0 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
221f0 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
22200 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
22210 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
22220 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
22230 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
22240 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
22250 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
22260 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
22270 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
22280 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
22290 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
222a0 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
222b0 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
222c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
222d0 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
222e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
222f0 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
22300 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
22310 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
22320 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
22330 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
22340 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
22350 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
22360 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
22370 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
22380 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
22390 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
223a0 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
223b0 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70  ter N is the app
223c0 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20  roximate number 
223d0 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
223e0 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
223f0 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
22400 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
22410 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
22420 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
22430 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e  e callback X.  ^
22440 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
22450 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70  n one then the p
22460 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c  rogress.** handl
22470 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  er is disabled..
22480 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
22490 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
224a0 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
224b0 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
224c0 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
224d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
224e0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
224f0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
22500 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
22510 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
22520 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
22530 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
22540 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
22550 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
22560 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
22570 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
22580 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
22590 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
225a0 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
225b0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
225c0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
225d0 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
225e0 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
225f0 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
22600 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
22610 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
22620 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
22630 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
22640 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
22650 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
22660 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
22670 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
22680 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
22690 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
226a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
226b0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
226c0 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
226d0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
226e0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
226f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
22700 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
22710 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
22720 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
22730 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
22740 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
22750 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
22760 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
22770 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
22780 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
22790 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
227a0 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
227b0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
227c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
227d0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
227e0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
227f0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ion.**.** ^These
22800 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
22810 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
22820 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
22830 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
22840 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
22850 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
22860 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
22870 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
22880 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
22890 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
228a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
228b0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
228c0 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
228d0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
228e0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
228f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
22900 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
22910 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
22920 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
22930 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
22940 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
22950 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
22960 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
22970 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
22980 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
22990 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
229a0 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
229b0 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
229c0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
229d0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
229e0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
229f0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
22a00 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
22a10 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
22a20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
22a30 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
22a40 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
22a50 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
22a60 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
22a70 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
22a80 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
22a90 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
22aa0 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
22ab0 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
22ac0 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
22ad0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
22ae0 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
22af0 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
22b00 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
22b10 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
22b20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
22b30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
22b40 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
22b50 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
22b60 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54  oding will be UT
22b70 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65  F-8 for database
22b80 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  s created using.
22b90 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
22ba0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
22bb0 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65  n_v2().  ^The de
22bc0 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
22bd0 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20  or databases.** 
22be0 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71  created using sq
22bf0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77  lite3_open16() w
22c00 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e  ill be UTF-16 in
22c10 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
22c20 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68   order..**.** Wh
22c30 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
22c40 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
22c50 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
22c60 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
22c70 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
22c80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
22c90 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
22ca0 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
22cb0 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
22cc0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
22cd0 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
22ce0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
22cf0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
22d00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22d10 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
22d20 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
22d30 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
22d40 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
22d50 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
22d60 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
22d70 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
22d80 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
22d90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22da0 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61  tion.  ^(The fla
22db0 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  gs parameter to.
22dc0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  ** sqlite3_open_
22dd0 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e  v2() can take on
22de0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
22df0 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75  owing three valu
22e00 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  es, optionally c
22e10 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65  ombined with the
22e20 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45   .** [SQLITE_OPE
22e30 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  N_NOMUTEX], [SQL
22e40 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
22e50 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
22e60 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a  N_SHAREDCACHE],.
22e70 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
22e80 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61  PRIVATECACHE], a
22e90 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
22ea0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e  EN_URI] flags:)^
22eb0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e  .**.** <dl>.** ^
22ec0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
22ed0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
22ee0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
22ef0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
22f00 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
22f10 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
22f20 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
22f30 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
22f40 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
22f50 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
22f60 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
22f70 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
22f80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
22f90 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
22fa0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
22fb0 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
22fc0 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
22fd0 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
22fe0 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
22ff0 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
23000 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
23010 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
23020 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
23030 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
23040 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
23050 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
23060 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
23070 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
23080 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
23090 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
230a0 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
230b0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
230c0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
230d0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
230e0 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
230f0 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  ed if.** it does
23100 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
23110 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20  st. This is the 
23120 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73  behavior that is
23130 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72   always used for
23140 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
23150 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
23160 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a  pen16().</dd>)^.
23170 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
23180 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
23190 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
231a0 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
231b0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
231c0 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
231d0 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c   above optionall
231e0 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
231f0 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  other.** [SQLITE
23200 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c  _OPEN_READONLY |
23210 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62   SQLITE_OPEN_* b
23220 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  its].** then the
23230 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
23240 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
23250 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
23260 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
23270 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
23280 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
23290 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
232a0 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
232b0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
232c0 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
232d0 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
232e0 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
232f0 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
23300 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
23310 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
23320 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
23330 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
23340 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
23350 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
23360 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
23370 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
23380 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
23390 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
233a0 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
233b0 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
233c0 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
233d0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
233e0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
233f0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
23400 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
23410 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
23420 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
23430 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
23440 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
23450 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
23460 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
23470 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
23480 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
23490 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
234a0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
234b0 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
234c0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
234d0 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
234e0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
234f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
23500 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
23510 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
23520 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
23530 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
23540 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
23550 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
23560 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23570 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
23580 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
23590 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
235a0 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
235b0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
235c0 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
235d0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
235e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
235f0 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65  ld use.  ^If the
23600 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
23610 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
23620 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
23630 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
23640 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
23650 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  used..**.** ^If 
23660 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
23670 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
23680 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
23690 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
236a0 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
236b0 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
236c0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69  onnection.  ^Thi
236d0 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
236e0 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
236f0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
23700 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23710 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
23720 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
23730 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
23740 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
23750 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
23760 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
23770 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
23780 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
23790 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
237a0 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
237b0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
237c0 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
237d0 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
237e0 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
237f0 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
23800 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
23810 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
23820 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
23830 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
23840 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
23850 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
23860 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
23870 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
23880 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
23890 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
238a0 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70  reated.  ^This p
238b0 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
238c0 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
238d0 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
238e0 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
238f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23900 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
23910 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
23920 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f  ames in sqlite3_
23930 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49  open()]] <h3>URI
23940 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a   Filenames</h3>.
23950 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66  **.** ^If [URI f
23960 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72  ilename] interpr
23970 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
23980 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65  ed, and the file
23990 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
239a0 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69   begins with "fi
239b0 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66  le:", then the f
239c0 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72  ilename is inter
239d0 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e  preted as a URI.
239e0 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d   ^URI.** filenam
239f0 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
23a00 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
23a10 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
23a20 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20  URI] flag is.** 
23a30 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74  set in the fourt
23a40 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
23a50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
23a60 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
23a70 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
23a80 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
23a90 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
23aa0 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
23ab0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
23ac0 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
23ad0 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
23ae0 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
23af0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
23b00 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74  ..** As of SQLit
23b10 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
23b20 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
23b30 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
23b40 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
23b50 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
23b60 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
23b70 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
23b80 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
23b90 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
23ba0 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
23bb0 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
23bc0 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
23bd0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
23be0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
23bf0 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
23c00 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
23c10 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
23c20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
23c30 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
23c40 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
23c50 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
23c60 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
23c70 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
23c80 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
23c90 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
23ca0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
23cb0 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
23cc0 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
23cd0 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
23ce0 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
23cf0 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
23d00 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
23d10 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
23d20 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
23d30 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
23d40 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
23d50 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
23d60 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
23d70 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
23d80 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
23d90 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
23da0 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
23db0 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
23dc0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
23dd0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
23de0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
23df0 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
23e00 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
23e10 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
23e20 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
23e30 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
23e40 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
23e50 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
23e60 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
23e70 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
23e80 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
23e90 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  (On windows, the
23ea0 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
23eb0 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
23ec0 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
23ed0 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
23ee0 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e  n (e.g. "C:").)^
23ef0 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
23f00 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
23f10 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
23f20 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
23f30 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
23f40 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
23f50 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
23f60 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
23f70 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
23f80 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
23f90 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
23fa0 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
23fb0 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d  e and its built-
23fc0 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72  in [VFSes] inter
23fd0 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  pret the.** foll
23fe0 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61  owing query para
23ff0 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
24000 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
24010 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
24020 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
24030 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
24040 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
24050 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
24060 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
24070 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
24080 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
24090 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
240a0 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
240b0 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
240c0 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
240d0 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
240e0 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
240f0 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
24100 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
24110 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
24120 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
24130 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
24140 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
24150 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
24160 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
24170 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
24180 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
24190 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
241a0 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
241b0 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
241c0 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
241d0 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
241e0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
241f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
24200 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
24210 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
24220 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
24230 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
24240 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
24250 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
24260 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
24270 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
24280 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
24290 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
242a0 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
242b0 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
242c0 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
242d0 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
242e0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
242f0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
24300 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
24310 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
24320 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
24330 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
24340 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
24350 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
24360 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
24370 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
24380 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
24390 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
243a0 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
243b0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
243c0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
243d0 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
243e0 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
243f0 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
24400 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
24410 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
24420 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
24430 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
24440 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
24450 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
24460 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
24470 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
24480 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
24490 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
244a0 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
244b0 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
244c0 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
244d0 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
244e0 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
244f0 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
24500 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
24510 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
24520 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
24530 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
24540 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
24550 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
24560 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
24570 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
24580 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
24590 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
245a0 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
245b0 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
245c0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
245d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
245e0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
245f0 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
24600 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
24610 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
24620 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
24630 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
24640 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
24650 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
24660 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
24670 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
24680 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
24690 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
246a0 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
246b0 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
246c0 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
246d0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
246e0 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
246f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
24700 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
24710 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
24720 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
24730 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
24740 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
24750 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
24760 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
24770 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
24780 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
24790 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
247a0 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
247b0 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
247c0 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
247d0 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
247e0 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
247f0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
24800 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
24810 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
24820 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  lag..**.**  <li>
24830 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54   <b>psow</b>: ^T
24840 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65  he psow paramete
24850 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74  r indicates whet
24860 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a  her or not the.*
24870 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65  *     [powersafe
24880 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70   overwrite] prop
24890 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65  erty does or doe
248a0 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74  s not apply to t
248b0 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67  he.**     storag
248c0 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68  e media on which
248d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
248e0 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a  le resides..**.*
248f0 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63  *  <li> <b>noloc
24900 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f  k</b>: ^The nolo
24910 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
24920 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20  a boolean query 
24930 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
24940 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69   which if set di
24950 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b  sables file lock
24960 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20  ing in rollback 
24970 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20  journal modes.  
24980 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75  This.**     is u
24990 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73  seful for access
249a0 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f  ing a database o
249b0 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74  n a filesystem t
249c0 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  hat does not.** 
249d0 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b      support lock
249e0 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20  ing.  Caution:  
249f0 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  Database corrupt
24a00 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ion might result
24a10 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f   if two.**     o
24a20 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73  r more processes
24a30 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61   write to the sa
24a40 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  me database and 
24a50 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65  any one of those
24a60 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65  .**     processe
24a70 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e  s uses nolock=1.
24a80 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
24a90 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e  immutable</b>: ^
24aa0 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61  The immutable pa
24ab0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
24ac0 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20  lean query.**   
24ad0 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74    parameter that
24ae0 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
24af0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
24b00 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a  e is stored on.*
24b10 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20  *     read-only 
24b20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d  media.  ^When im
24b30 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20  mutable is set, 
24b40 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
24b50 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64  hat the.**     d
24b60 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e  atabase file can
24b70 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20  not be changed, 
24b80 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73  even by a proces
24b90 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a  s with higher.**
24ba0 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20       privilege, 
24bb0 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62  and so the datab
24bc0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65  ase is opened re
24bd0 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20  ad-only and all 
24be0 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61  locking.**     a
24bf0 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74  nd change detect
24c00 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ion is disabled.
24c10 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69    Caution: Setti
24c20 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65  ng the immutable
24c30 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79  .**     property
24c40 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66   on a database f
24c50 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e  ile that does in
24c60 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e   fact change can
24c70 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69   result.**     i
24c80 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72  n incorrect quer
24c90 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72  y results and/or
24ca0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
24cb0 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20  ] errors..**    
24cc0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
24cd0 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
24ce0 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a  LE]..**       .*
24cf0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
24d00 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
24d10 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
24d20 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
24d30 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
24d40 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
24d50 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
24d60 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
24d70 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
24d80 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
24d90 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
24da0 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
24db0 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
24dc0 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
24dd0 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
24de0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
24df0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
24e00 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
24e10 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
24e20 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
24e30 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
24e40 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
24e50 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
24e60 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
24e70 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
24e80 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
24e90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
24ea0 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
24eb0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
24ec0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
24ed0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
24ee0 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
24ef0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
24f00 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
24f10 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
24f20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
24f30 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
24f40 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
24f50 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
24f60 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
24f70 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
24f80 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
24f90 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
24fa0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
24fb0 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
24fc0 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
24fd0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
24fe0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
24ff0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
25000 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
25010 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
25020 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
25030 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
25040 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
25050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
25060 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
25070 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
25080 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
25090 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
250a0 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
250b0 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
250c0 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
250d0 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
250e0 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
250f0 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
25100 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
25110 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
25120 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
25130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
25140 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
25150 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
25160 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
25170 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
25180 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
25190 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
251a0 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
251b0 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
251c0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
251d0 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
251e0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
251f0 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
25200 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
25210 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
25220 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
25230 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
25240 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
25250 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
25260 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
25270 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
25280 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
25290 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
252a0 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
252b0 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a  x-dotfile <td>.*
252c0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
252d0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
252e0 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
252f0 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
25300 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a  unix-dotfile".**
25310 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75            that u
25320 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e  ses dot-files in
25330 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20   place of posix 
25340 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67  advisory locking
25350 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
25360 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
25370 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
25380 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
25390 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
253a0 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
253b0 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
253c0 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
253d0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
253e0 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
253f0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
25400 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
25410 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
25420 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
25430 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
25440 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
25450 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
25460 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
25470 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
25480 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
25490 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
254a0 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
254b0 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
254c0 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
254d0 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
254e0 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
254f0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
25500 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
25510 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
25520 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
25530 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
25540 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
25550 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
25560 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
25570 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
25580 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
25590 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
255a0 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
255b0 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
255c0 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
255d0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
255e0 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
255f0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
25600 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
25610 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
25620 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
25630 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
25640 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
25650 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
25660 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
25670 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
25680 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
25690 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
256a0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
256b0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
256c0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
256d0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
256e0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
256f0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
25700 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
25710 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
25720 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
25730 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
25740 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
25750 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
25760 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
25770 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
25780 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
25790 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
257a0 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
257b0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
257c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
257d0 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
257e0 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
257f0 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
25800 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
25810 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
25820 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
25830 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
25840 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53  _directory].*/.S
25850 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
25860 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
25870 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
25880 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
25890 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
258a0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
258b0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
258c0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
258d0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53  b handle */.);.S
258e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
258f0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
25900 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
25910 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
25920 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
25930 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
25940 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
25950 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
25960 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
25970 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
25980 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25990 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
259a0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
259b0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
259c0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
259d0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
259e0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
259f0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
25a00 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
25a10 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
25a20 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
25a30 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
25a40 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
25a50 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
25a60 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
25a70 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
25a80 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
25a90 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
25aa0 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
25ab0 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
25ac0 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
25ad0 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
25ae0 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
25af0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
25b00 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
25b10 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
25b20 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
25b30 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
25b40 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
25b50 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
25b60 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
25b70 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
25b80 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
25b90 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
25ba0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
25bb0 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
25bc0 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
25bd0 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
25be0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
25bf0 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
25c00 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
25c10 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
25c20 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
25c30 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
25c40 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
25c50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
25c60 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
25c70 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
25c80 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
25c90 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
25ca0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
25cb0 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
25cc0 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
25cd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
25ce0 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
25cf0 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
25d00 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
25d10 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
25d20 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
25d30 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
25d40 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
25d50 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
25d60 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
25d70 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
25d80 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
25d90 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
25da0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
25db0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
25dc0 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
25dd0 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
25de0 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
25df0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
25e00 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
25e10 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
25e20 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
25e30 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
25e40 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
25e50 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
25e60 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
25e70 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
25e80 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
25e90 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
25ea0 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
25eb0 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
25ec0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
25ed0 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
25ee0 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
25ef0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
25f00 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
25f10 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
25f20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
25f30 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
25f40 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
25f50 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
25f60 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
25f70 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
25f80 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
25f90 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
25fa0 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
25fb0 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
25fc0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
25fd0 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
25fe0 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
25ff0 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
26000 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
26010 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
26020 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
26030 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
26040 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26050 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
26060 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
26070 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
26080 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
26090 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
260a0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
260b0 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
260c0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
260d0 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
260e0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
260f0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
26100 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
26110 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
26120 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
26130 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
26140 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
26150 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
26160 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
26170 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
26180 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
26190 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
261a0 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
261b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
261c0 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
261d0 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
261e0 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
261f0 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
26200 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
26210 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
26220 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
26230 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
26240 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
26250 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
26260 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51  desirable..*/.SQ
26270 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
26280 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69  har *sqlite3_uri
26290 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74  _parameter(const
262a0 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
262b0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
262c0 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50  aram);.SQLITE_AP
262d0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72  I int sqlite3_ur
262e0 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20  i_boolean(const 
262f0 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e  char *zFile, con
26300 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c  st char *zParam,
26310 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a   int bDefault);.
26320 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
26330 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
26340 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
26350 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
26360 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
26370 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
26380 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
26390 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
263a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
263b0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
263c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
263d0 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
263e0 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
263f0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
26400 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
26410 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
26420 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
26430 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
26440 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
26450 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
26460 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
26470 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
26480 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
26490 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
264a0 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
264b0 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
264c0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
264d0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
264e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
264f0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
26500 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
26510 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
26520 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
26530 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
26540 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
26550 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
26560 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
26570 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
26580 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
26590 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
265a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
265b0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
265c0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
265d0 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
265e0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
265f0 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
26600 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
26610 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
26620 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
26630 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
26640 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
26650 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
26660 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
26670 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
26680 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
26690 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
266a0 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
266b0 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
266c0 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
266d0 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
266e0 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
266f0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
26700 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
26710 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
26720 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
26730 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
26740 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
26750 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
26760 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
26770 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
26780 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
26790 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
267a0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
267b0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
267c0 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
267d0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
267e0 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
267f0 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
26800 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
26810 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
26820 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
26830 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
26840 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
26850 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
26860 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
26870 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
26880 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
26890 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
268a0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
268b0 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
268c0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
268d0 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
268e0 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
268f0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
26900 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
26910 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
26920 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
26930 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
26940 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
26950 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
26960 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
26970 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
26980 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
26990 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
269a0 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
269b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
269c0 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
269d0 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
269e0 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
269f0 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
26a00 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
26a10 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
26a20 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
26a30 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
26a40 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
26a50 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
26a60 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
26a70 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
26a80 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
26a90 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
26aa0 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
26ab0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
26ac0 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
26ad0 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
26ae0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
26af0 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
26b00 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
26b10 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
26b20 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
26b30 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
26b40 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  I int sqlite3_er
26b50 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
26b60 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  b);.SQLITE_API i
26b70 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
26b80 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
26b90 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
26ba0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
26bb0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
26bc0 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54  sqlite3*);.SQLIT
26bd0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
26be0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
26bf0 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  16(sqlite3*);.SQ
26c00 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
26c10 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
26c20 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  str(int);../*.**
26c30 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
26c40 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
26c50 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
26c60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26c70 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
26c80 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
26c90 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
26ca0 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
26cb0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
26cc0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
26cd0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
26ce0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
26cf0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
26d00 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
26d10 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
26d20 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
26d30 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
26d40 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
26d50 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
26d60 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
26d70 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
26d80 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
26d90 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
26da0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
26db0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
26dc0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
26dd0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
26de0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
26df0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
26e00 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
26e10 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
26e20 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
26e30 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
26e40 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
26e50 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
26e60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
26e70 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
26e80 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
26e90 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
26ea0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
26eb0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
26ec0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
26ed0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
26ee0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
26ef0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
26f00 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
26f10 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
26f20 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
26f30 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
26f40 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
26f50 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
26f60 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
26f70 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
26f80 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
26f90 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
26fa0 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
26fb0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
26fc0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
26fd0 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
26fe0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
26ff0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
27000 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
27010 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
27020 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
27030 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
27040 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
27050 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
27060 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
27070 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
27080 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
27090 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
270a0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
270b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
270c0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
270d0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
270e0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
270f0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
27100 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
27110 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
27120 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
27130 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
27140 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
27150 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
27160 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
27170 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
27180 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
27190 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
271a0 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
271b0 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
271c0 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
271d0 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
271e0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
271f0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
27200 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
27210 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
27220 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
27230 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
27240 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
27250 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
27260 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
27270 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
27280 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
27290 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
272a0 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
272b0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
272c0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
272d0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
272e0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
272f0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
27300 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
27310 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
27320 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
27330 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
27340 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
27350 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
27360 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
27370 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
27380 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
27390 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
273a0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
273b0 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
273c0 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
273d0 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
273e0 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
273f0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
27400 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
27410 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
27420 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
27430 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
27440 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
27450 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
27460 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
27470 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
27480 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
27490 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
274a0 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
274b0 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
274c0 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
274d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
274e0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
274f0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
27500 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
27510 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
27520 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
27530 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
27540 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
27550 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
27560 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
27570 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
27580 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
27590 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
275a0 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
275b0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
275c0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
275d0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
275e0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
275f0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
27600 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
27610 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
27620 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
27630 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
27640 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
27650 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
27660 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
27670 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
27680 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
27690 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
276a0 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
276b0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
276c0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
276d0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
276e0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
276f0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
27700 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
27710 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
27720 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
27730 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
27740 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
27750 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
27760 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
27770 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
27780 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
27790 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
277a0 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
277b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
277c0 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
277d0 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
277e0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
277f0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
27800 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
27810 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
27820 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
27830 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
27840 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
27850 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
27860 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
27870 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
27880 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
27890 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
278a0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
278b0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
278c0 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
278d0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
278e0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
278f0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
27900 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
27910 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
27920 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
27930 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
27940 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
27950 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
27960 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
27970 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
27980 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
27990 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
279a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
279b0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
279c0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
279d0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
279e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
279f0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
27a00 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
27a10 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
27a20 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
27a30 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
27a40 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27a50 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
27a60 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
27a70 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
27a80 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
27a90 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
27aa0 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
27ab0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
27ac0 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
27ad0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
27ae0 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
27af0 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
27b00 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
27b10 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
27b20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
27b30 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
27b40 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
27b50 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
27b60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
27b70 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
27b80 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
27b90 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
27ba0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
27bb0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
27bc0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
27bd0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
27be0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
27bf0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
27c00 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
27c10 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
27c20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
27c30 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
27c40 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
27c50 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
27c60 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
27c70 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
27c80 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
27c90 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
27ca0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
27cb0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
27cc0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
27cd0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
27ce0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
27cf0 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
27d00 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
27d10 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
27d20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
27d30 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
27d40 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
27d50 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
27d60 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
27d70 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
27d80 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
27d90 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
27da0 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
27db0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
27dc0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
27dd0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
27de0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
27df0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
27e00 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
27e10 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
27e20 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
27e30 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
27e40 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
27e50 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
27e60 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
27e70 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
27e80 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
27e90 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
27ea0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
27eb0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
27ec0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
27ed0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
27ee0 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
27ef0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
27f00 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
27f10 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
27f20 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
27f30 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
27f40 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
27f50 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
27f60 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
27f70 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27f80 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
27f90 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
27fa0 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
27fb0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
27fc0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
27fd0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
27fe0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
27ff0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
28000 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
28010 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
28020 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
28030 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
28040 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
28050 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
28060 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74  _THREADS]] ^(<dt
28070 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  >SQLITE_LIMIT_WO
28080 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74  RKER_THREADS</dt
28090 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
280a0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
280b0 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20  uxiliary worker 
280c0 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73  threads that a s
280d0 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72  ingle.** [prepar
280e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61  ed statement] ma
280f0 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a  y start.</dd>)^.
28100 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
28110 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
28120 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
28130 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
28140 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
28150 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
28160 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
28170 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
28180 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
28190 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
281a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
281b0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
281c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
281d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
281e0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
281f0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
28200 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
28210 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
28220 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28230 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
28240 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
28250 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
28260 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
28270 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
28280 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28290 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
282a0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
282b0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
282c0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
282d0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
282e0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
282f0 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
28300 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
28310 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
28320 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
28330 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
28340 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20  ER_THREADS      
28350 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43       11../*.** C
28360 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
28370 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
28380 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
28390 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
283a0 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
283b0 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
283c0 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
283d0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
283e0 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
283f0 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
28400 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
28410 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
28420 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
28430 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
28440 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
28450 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
28460 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
28470 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
28480 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
28490 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
284a0 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
284b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
284c0 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
284d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
284e0 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
284f0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
28500 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
28510 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
28520 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
28530 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
28540 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
28550 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
28560 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
28570 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
28580 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
28590 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
285a0 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
285b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
285c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
285d0 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
285e0 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
285f0 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
28600 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
28610 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
28620 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
28630 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
28640 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
28650 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e  . ^If nByte is n
28660 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
28670 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
28680 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
28690 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
286a0 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e  m zSql.  ^When n
286b0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
286c0 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
286d0 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
286e0 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
286f0 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
28700 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
28710 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
28720 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
28730 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
28740 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
28750 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
28760 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
28770 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
28780 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
28790 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
287a0 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
287b0 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
287c0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
287d0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
287e0 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
287f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
28800 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
28810 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
28820 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
28830 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
28840 79 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76  ytes as this sav
28850 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68  es SQLite from h
28860 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65  aving to.** make
28870 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69   a copy of the i
28880 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  nput string..**.
28890 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
288a0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
288b0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
288c0 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
288d0 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
288e0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
288f0 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
28900 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
28910 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
28920 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
28930 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
28940 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
28950 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
28960 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
28970 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
28980 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
28990 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
289a0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
289b0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
289c0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
289d0 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
289e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
289f0 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
28a00 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
28a10 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
28a20 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
28a30 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
28a40 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
28a50 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
28a60 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
28a70 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
28a80 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
28a90 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
28aa0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
28ab0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
28ac0 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
28ad0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
28ae0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
28af0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
28b00 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
28b10 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
28b20 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
28b30 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
28b40 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
28b50 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
28b60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
28b70 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
28b80 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
28b90 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
28ba0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
28bb0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
28bc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
28bd0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
28be0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
28bf0 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
28c00 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
28c10 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
28c20 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
28c30 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
28c40 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
28c50 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
28c60 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
28c70 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
28c80 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
28c90 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
28ca0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
28cb0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
28cc0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
28cd0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
28ce0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
28cf0 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
28d00 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
28d10 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
28d20 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
28d30 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
28d40 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
28d50 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
28d60 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
28d70 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
28d80 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
28d90 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
28da0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
28db0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
28dc0 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
28dd0 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
28de0 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
28df0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
28e00 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
28e10 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
28e20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
28e30 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
28e40 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e  it again. As man
28e50 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58  y as [SQLITE_MAX
28e60 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a  _SCHEMA_RETRY].*
28e70 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f  * retries will o
28e80 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69  ccur before sqli
28e90 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73  te3_step() gives
28ea0 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20   up and returns 
28eb0 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c  an error..** </l
28ec0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
28ed0 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
28ee0 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
28ef0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
28f00 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
28f10 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
28f20 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
28f30 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
28f40 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
28f50 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
28f60 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
28f70 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
28f80 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
28f90 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
28fa0 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
28fb0 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
28fc0 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
28fd0 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
28fe0 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
28ff0 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
29000 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
29010 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
29020 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
29030 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
29040 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
29050 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
29060 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
29070 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
29080 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
29090 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
290a0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
290b0 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
290c0 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
290d0 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
290e0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
290f0 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
29100 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
29110 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
29120 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
29130 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
29140 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
29150 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
29160 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
29170 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
29180 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
29190 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
291a0 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
291b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
291c0 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
291d0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
291e0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
291f0 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
29200 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
29210 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
29220 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
29230 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
29240 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
29250 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
29260 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
29270 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
29280 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
29290 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
292a0 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
292b0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
292c0 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
292d0 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
292e0 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
292f0 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
29300 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
29310 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
29320 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
29330 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  bled..** </li>.*
29340 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54  * </ol>.*/.SQLIT
29350 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
29360 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
29370 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
29380 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
29390 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
293a0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
293b0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
293c0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
293d0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
293e0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
293f0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
29400 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
29410 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
29420 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
29430 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
29440 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
29450 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
29460 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
29470 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
29480 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
29490 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
294a0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
294b0 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
294c0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
294d0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
294e0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
294f0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
29500 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
29510 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
29520 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
29530 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
29540 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
29550 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
29560 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
29570 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
29580 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
29590 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
295a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
295b0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
295c0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
295d0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
295e0 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
295f0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
29600 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
29610 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
29620 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
29630 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
29640 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
29650 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
29660 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
29670 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
29680 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
29690 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
296a0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
296b0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
296c0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
296d0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
296e0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
296f0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
29700 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
29710 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
29720 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
29730 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
29740 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
29750 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
29760 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
29770 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
29780 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
29790 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
297a0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
297b0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
297c0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
297d0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
297e0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
297f0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
29800 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
29810 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
29820 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
29830 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
29840 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
29850 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
29860 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
29870 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
29880 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
29890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
298a0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
298b0 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
298c0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
298d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
298e0 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
298f0 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
29900 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
29910 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
29920 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29930 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
29940 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
29950 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
29960 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
29970 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
29980 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
29990 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  6_v2()]..*/.SQLI
299a0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
299b0 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
299c0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
299d0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
299e0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
299f0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
29a00 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
29a10 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54  atabase.**.** ^T
29a20 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
29a30 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
29a40 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
29a50 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
29a60 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
29a70 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
29a80 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
29a90 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
29aa0 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
29ab0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
29ac0 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
29ad0 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
29ae0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
29af0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
29b00 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
29b10 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
29b20 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
29b30 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
29b40 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
29b50 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
29b60 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
29b70 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
29b80 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
29b90 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
29ba0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
29bb0 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
29bc0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
29bd0 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
29be0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
29bf0 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
29c00 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
29c10 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
29c20 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
29c30 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
29c40 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
29c50 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
29c60 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
29c70 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
29c80 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
29c90 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
29ca0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
29cb0 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
29cc0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
29cd0 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
29ce0 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
29cf0 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
29d00 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
29d10 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
29d20 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
29d30 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
29d40 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
29d50 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
29d60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
29d70 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
29d80 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
29d90 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
29da0 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
29db0 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
29dc0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
29dd0 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
29de0 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
29df0 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
29e00 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
29e10 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
29e20 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
29e30 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
29e40 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
29e50 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
29e60 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
29e70 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
29e80 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
29e90 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
29ea0 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
29eb0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
29ec0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
29ed0 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
29ee0 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
29ef0 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
29f00 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
29f10 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
29f20 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  k..*/.SQLITE_API
29f30 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d   int sqlite3_stm
29f40 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
29f50 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
29f60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29f70 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
29f80 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
29f90 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
29fa0 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  et.**.** ^The sq
29fb0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
29fc0 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  S) interface ret
29fd0 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
29fe0 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b  ero) if the.** [
29ff0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a000 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73  nt] S has been s
2a010 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20  tepped at least 
2a020 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  once using .** [
2a030 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2a040 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e   but has not run
2a050 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
2a060 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a  nd/or has not .*
2a070 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69  * been reset usi
2a080 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2a090 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c  t(S)].  ^The sql
2a0a0 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
2a0b0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
2a0c0 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20  eturns false if 
2a0d0 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
2a0e0 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f  ter.  If S is no
2a0f0 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  t a .** NULL poi
2a100 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20  nter and is not 
2a110 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
2a120 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73  alid [prepared s
2a130 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
2a140 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ect, then the be
2a150 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2a160 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
2a170 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a   undesirable..**
2a180 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2a190 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ce can be used i
2a1a0 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73  n combination [s
2a1b0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
2a1c0 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65  ()].** to locate
2a1d0 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74   all prepared st
2a1e0 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
2a1f0 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62  ted with a datab
2a200 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  ase .** connecti
2a210 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e  on that are in n
2a220 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73  eed of being res
2a230 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65  et.  This can be
2a240 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78   used,.** for ex
2a250 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f  ample, in diagno
2a260 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f  stic routines to
2a270 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70   search for prep
2a280 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65  ared .** stateme
2a290 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c  nts that are hol
2a2a0 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ding a transacti
2a2b0 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49  on open..*/.SQLI
2a2c0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2a2d0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c  e3_stmt_busy(sql
2a2e0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2a2f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
2a300 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
2a310 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
2a320 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
2a330 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2a340 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
2a350 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
2a360 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
2a370 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
2a380 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
2a390 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
2a3a0 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
2a3b0 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
2a3c0 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
2a3d0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
2a3e0 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
2a3f0 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
2a400 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
2a410 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
2a420 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
2a430 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
2a440 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
2a450 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
2a460 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
2a470 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
2a480 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2a490 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
2a4a0 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
2a4b0 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
2a4c0 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
2a4d0 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
2a4e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2a4f0 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
2a500 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
2a510 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
2a520 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
2a530 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2a540 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
2a550 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
2a560 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
2a570 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
2a580 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
2a590 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
2a5a0 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
2a5b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2a5c0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
2a5d0 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
2a5e0 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
2a5f0 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
2a600 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
2a610 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
2a620 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
2a630 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
2a640 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2a650 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2a660 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
2a670 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
2a680 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2a690 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
2a6a0 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
2a6b0 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
2a6c0 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
2a6d0 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
2a6e0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
2a6f0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
2a700 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
2a710 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
2a720 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
2a730 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
2a740 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
2a750 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
2a760 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
2a770 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2a780 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
2a790 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
2a7a0 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
2a7b0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
2a7c0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
2a7d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2a7e0 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
2a7f0 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
2a800 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
2a810 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
2a820 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
2a830 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
2a840 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
2a850 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
2a860 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
2a870 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
2a880 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
2a890 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
2a8a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2a8b0 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
2a8c0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
2a8d0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
2a8e0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2a8f0 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
2a900 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
2a910 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
2a920 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
2a930 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
2a940 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2a950 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
2a960 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
2a970 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2a980 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2a990 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2a9a0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2a9b0 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
2a9c0 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
2a9d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2a9e0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
2a9f0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
2aa00 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2aa10 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2aa20 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
2aa30 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
2aa40 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
2aa50 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
2aa60 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
2aa70 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
2aa80 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
2aa90 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2aaa0 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
2aab0 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
2aac0 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
2aad0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
2aae0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
2aaf0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
2ab00 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
2ab10 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
2ab20 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
2ab30 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
2ab40 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
2ab50 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
2ab60 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
2ab70 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
2ab80 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
2ab90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
2aba0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2abb0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2abc0 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
2abd0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2abe0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
2abf0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
2ac00 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
2ac10 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
2ac20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2ac30 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
2ac40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
2ac50 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
2ac60 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2ac70 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
2ac80 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
2ac90 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2aca0 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
2acb0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2acc0 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
2acd0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
2ace0 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
2acf0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
2ad00 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
2ad10 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
2ad20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
2ad30 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
2ad40 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2ad50 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
2ad60 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2ad70 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2ad80 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
2ad90 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
2ada0 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
2adb0 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
2adc0 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
2add0 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a  er binding}.**.*
2ade0 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
2adf0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
2ae00 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
2ae10 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2ae20 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
2ae30 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
2ae40 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
2ae50 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
2ae60 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
2ae70 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
2ae80 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
2ae90 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
2aea0 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
2aeb0 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
2aec0 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
2aed0 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
2aee0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
2aef0 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
2af00 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
2af10 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
2af20 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
2af30 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
2af40 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
2af50 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
2af60 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
2af70 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
2af80 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
2af90 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
2afa0 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
2afb0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
2afc0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
2afd0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2afe0 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
2aff0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2b000 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2b010 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2b020 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
2b030 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
2b040 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
2b050 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
2b060 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
2b070 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2b080 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
2b090 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
2b0a0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
2b0b0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2b0c0 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
2b0d0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
2b0e0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
2b0f0 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
2b100 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2b110 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
2b120 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
2b130 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
2b140 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
2b150 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
2b160 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
2b170 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
2b180 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
2b190 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
2b1a0 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
2b1b0 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
2b1c0 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
2b1d0 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
2b1e0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
2b1f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2b200 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
2b210 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
2b220 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
2b230 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
2b240 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
2b250 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
2b260 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
2b270 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
2b280 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
2b290 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
2b2a0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2b2b0 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
2b2c0 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
2b2d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
2b2e0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2b2f0 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
2b300 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2b310 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
2b320 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2b330 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2b340 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
2b350 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
2b360 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2b370 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c  blob() is a NULL
2b380 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
2b390 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2b3a0 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64  er.** is ignored
2b3b0 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73   and the end res
2b3c0 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20  ult is the same 
2b3d0 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  as sqlite3_bind_
2b3e0 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  null()..**.** ^(
2b3f0 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
2b400 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
2b410 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
2b420 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
2b430 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
2b440 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
2b450 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
2b460 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
2b470 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2b480 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
2b490 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
2b4a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2b4b0 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
2b4c0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2b4d0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2b4e0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2b4f0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2b500 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65  ext16().** is ne
2b510 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
2b520 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
2b530 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
2b540 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2b550 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
2b560 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2b570 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
2b580 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2b590 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b5a0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  () is negative, 
2b5b0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61  then.** the beha
2b5c0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2b5d0 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  d..** If a non-n
2b5e0 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
2b5f0 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
2b600 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
2b610 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
2b620 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2b630 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74  ext16() or sqlit
2b640 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2b650 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61   then.** that pa
2b660 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
2b670 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a  the byte offset.
2b680 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ** where the NUL
2b690 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
2b6a0 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67  d occur assuming
2b6b0 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65   the string were
2b6c0 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74   NUL.** terminat
2b6d0 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
2b6e0 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
2b6f0 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73   at byte offsets
2b700 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74   less than .** t
2b710 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2b720 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2b730 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2b740 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65  ing string value
2b750 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e   will.** contain
2b760 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20   embedded NULs. 
2b770 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65   The result of e
2b780 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c  xpressions invol
2b790 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ving strings.** 
2b7a0 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
2b7b0 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
2b7c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
2b7d0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
2b7e0 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e  e BLOB and strin
2b7f0 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66  g binding interf
2b800 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73  aces.** is a des
2b810 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
2b820 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2b830 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
2b840 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
2b850 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2b860 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
2b870 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
2b880 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
2b890 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
2b8a0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
2b8b0 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20  all to bind API 
2b8c0 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  fails..** ^If th
2b8d0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2b8e0 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
2b8f0 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
2b900 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
2b910 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
2b920 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
2b930 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
2b940 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
2b950 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
2b960 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
2b970 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
2b980 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
2b990 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
2b9a0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
2b9b0 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
2b9c0 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
2b9d0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2b9e0 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
2b9f0 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
2ba00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2ba10 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2ba20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ..**.** ^The six
2ba30 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2ba40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2ba50 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  64() must be one
2ba60 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   of.** [SQLITE_U
2ba70 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
2ba80 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  F16], [SQLITE_UT
2ba90 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49  F16BE], or [SQLI
2baa0 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74  TE_UTF16LE].** t
2bab0 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e  o specify the en
2bac0 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65  coding of the te
2bad0 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  xt in the third 
2bae0 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a  parameter.  If.*
2baf0 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75  * the sixth argu
2bb00 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2bb10 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73  bind_text64() is
2bb20 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
2bb30 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65  ** allowed value
2bb40 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f  s shown above, o
2bb50 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e  r if the text en
2bb60 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
2bb70 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ent.** from the 
2bb80 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
2bb90 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20  ed by the sixth 
2bba0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
2bbb0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2bbc0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2bbd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2bbe0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
2bbf0 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
2bc00 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
2bc10 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
2bc20 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
2bc30 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
2bc40 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
2bc50 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
2bc60 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
2bc70 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
2bc80 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
2bc90 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
2bca0 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
2bcb0 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
2bcc0 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
2bcd0 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
2bce0 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
2bcf0 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
2bd00 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2bd10 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
2bd20 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
2bd30 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
2bd40 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
2bd50 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
2bd60 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
2bd70 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
2bd80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
2bd90 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
2bda0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2bdb0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
2bdc0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2bdd0 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
2bde0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
2bdf0 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
2be00 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
2be10 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
2be20 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
2be30 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
2be40 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
2be50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
2be60 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
2be70 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
2be80 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
2be90 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
2bea0 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
2beb0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
2bec0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bed0 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
2bee0 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
2bef0 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
2bf00 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2bf10 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
2bf20 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
2bf30 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
2bf40 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2bf50 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
2bf60 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
2bf70 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
2bf80 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
2bf90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2bfa0 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
2bfb0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2bfc0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
2bfd0 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
2bfe0 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
2bff0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
2c000 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
2c010 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2c020 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
2c030 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
2c040 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
2c050 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
2c060 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
2c070 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2c080 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
2c090 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
2c0a0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
2c0b0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
2c0c0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2c0d0 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
2c0e0 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
2c0f0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
2c100 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
2c110 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
2c120 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2c130 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2c140 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
2c150 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2c160 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2c170 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
2c180 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2c190 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
2c1a0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2c1b0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
2c1c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2c1d0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2c1e0 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
2c1f0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
2c200 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2c210 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  _blob64(sqlite3_
2c220 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2c230 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  t void*, sqlite3
2c240 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
2c250 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c260 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2c270 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2c280 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
2c290 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2c2a0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
2c2b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2c2c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
2c2d0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2c2e0 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49   int, int);.SQLI
2c2f0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2c300 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
2c310 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c320 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
2c330 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2c340 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
2c350 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
2c360 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
2c370 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2c380 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
2c390 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74  _stmt*,int,const
2c3a0 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28   char*,int,void(
2c3b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
2c3c0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2c3d0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
2c3e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2c3f0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2c400 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2c410 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
2c420 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2c430 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33  d_text64(sqlite3
2c440 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2c450 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
2c460 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2c470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c480 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2c490 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  ), unsigned char
2c4a0 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49   encoding);.SQLI
2c4b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2c4c0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
2c4d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c4e0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
2c4f0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
2c500 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2c510 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
2c520 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c530 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
2c540 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2c550 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
2c560 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ers.**.** ^This 
2c570 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
2c580 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
2c590 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
2c5a0 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
2c5b0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2c5c0 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
2c5d0 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
2c5e0 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
2c5f0 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
2c600 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
2c610 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
2c620 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
2c630 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
2c640 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
2c650 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2c660 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
2c670 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
2c680 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
2c690 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
2c6a0 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
2c6b0 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
2c6c0 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
2c6d0 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
2c6e0 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
2c6f0 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
2c700 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
2c710 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
2c720 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
2c730 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
2c740 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
2c750 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
2c760 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
2c770 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
2c780 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
2c790 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2c7a0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2c7b0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2c7c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2c7d0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2c7e0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2c7f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2c800 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2c810 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2c820 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2c830 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
2c840 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2c850 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
2c860 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
2c870 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  meter.**.** ^The
2c880 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2c890 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
2c8a0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2c8b0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
2c8c0 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
2c8d0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2c8e0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2c8f0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
2c900 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
2c910 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
2c920 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2c930 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2c940 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
2c950 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
2c960 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
2c970 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2c980 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
2c990 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
2c9a0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
2c9b0 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
2c9c0 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
2c9d0 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
2c9e0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
2c9f0 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
2ca00 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2ca10 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
2ca20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
2ca30 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
2ca40 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
2ca50 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
2ca60 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
2ca70 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
2ca80 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2ca90 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
2caa0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2cab0 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
2cac0 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
2cad0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
2cae0 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
2caf0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
2cb00 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
2cb10 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
2cb20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2cb30 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
2cb40 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
2cb50 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
2cb60 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
2cb70 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
2cb80 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
2cb90 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
2cba0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
2cbb0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2cbc0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2cbd0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2cbe0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2cbf0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2cc00 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2cc10 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2cc20 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
2cc30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2cc40 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2cc50 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
2cc60 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2cc70 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2cc80 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
2cc90 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
2cca0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
2ccb0 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
2ccc0 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
2ccd0 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  ame.**.** ^Retur
2cce0 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
2ccf0 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
2cd00 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
2cd10 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
2cd20 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
2cd30 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
2cd40 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
2cd50 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
2cd60 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2cd70 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2cd80 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
2cd90 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
2cda0 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
2cdb0 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
2cdc0 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
2cdd0 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
2cde0 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
2cdf0 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
2ce00 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
2ce10 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
2ce20 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
2ce30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
2ce40 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2ce50 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2ce60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2ce70 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2ce80 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2ce90 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2cea0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2ceb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2cec0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2ced0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2cee0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2cef0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
2cf00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
2cf10 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
2cf20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2cf30 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
2cf40 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
2cf50 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
2cf60 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
2cf70 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
2cf80 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
2cf90 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
2cfa0 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
2cfb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2cfc0 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
2cfd0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2cfe0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
2cff0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
2d000 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
2d010 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
2d020 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ULL..*/.SQLITE_A
2d030 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2d040 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
2d050 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2d060 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2d070 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
2d080 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2d090 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2d0a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2d0b0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2d0c0 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
2d0d0 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
2d0e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2d0f0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
2d100 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
2d110 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
2d120 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
2d130 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
2d140 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
2d150 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
2d160 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2d170 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2d180 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ()].*/.SQLITE_AP
2d190 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
2d1a0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
2d1b0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2d1c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d1d0 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
2d1e0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2d1f0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2d200 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2d210 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
2d220 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
2d230 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
2d240 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
2d250 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2d260 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
2d270 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
2d280 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
2d290 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2d2a0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2d2b0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
2d2c0 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
2d2d0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
2d2e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2d2f0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2d300 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
2d310 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
2d320 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2d330 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2d340 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
2d350 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2d360 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2d370 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
2d380 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2d390 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
2d3a0 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
2d3b0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
2d3c0 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
2d3d0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2d3e0 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
2d3f0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
2d400 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2d410 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
2d420 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
2d430 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2d440 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2d450 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2d460 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2d470 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2d480 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2d490 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2d4a0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2d4b0 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2d4c0 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
2d4d0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2d4e0 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
2d4f0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2d500 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
2d510 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
2d520 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
2d530 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
2d540 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
2d550 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
2d560 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
2d570 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
2d580 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
2d590 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
2d5a0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
2d5b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2d5c0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
2d5d0 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
2d5e0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2d5f0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
2d600 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
2d610 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
2d620 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
2d630 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
2d640 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
2d650 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2d660 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
2d670 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
2d680 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
2d690 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
2d6a0 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
2d6b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
2d6c0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2d6d0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
2d6e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d6f0 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t N);.SQLITE_API
2d700 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2d710 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2d720 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2d730 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
2d740 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
2d750 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
2d760 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
2d770 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2d780 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
2d790 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
2d7a0 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
2d7b0 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
2d7c0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
2d7d0 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
2d7e0 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
2d7f0 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
2d800 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2d810 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
2d820 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2d830 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
2d840 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
2d850 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
2d860 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
2d870 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2d880 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
2d890 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
2d8a0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
2d8b0 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
2d8c0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2d8d0 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
2d8e0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
2d8f0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2d900 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
2d910 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2d920 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
2d930 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
2d940 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d950 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
2d960 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2d970 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2d980 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2d990 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2d9a0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2d9b0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2d9c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2d9d0 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2d9e0 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2d9f0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
2da00 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
2da10 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
2da20 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
2da30 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
2da40 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
2da50 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
2da60 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
2da70 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
2da80 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
2da90 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
2daa0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2dab0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2dac0 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
2dad0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2dae0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
2daf0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
2db00 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2db10 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
2db20 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
2db30 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
2db40 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
2db50 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
2db60 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
2db70 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
2db80 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
2db90 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
2dba0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
2dbb0 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
2dbc0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2dbd0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2dbe0 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
2dbf0 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
2dc00 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
2dc10 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
2dc20 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
2dc30 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
2dc40 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
2dc50 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
2dc60 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
2dc70 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2dc80 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
2dc90 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
2dca0 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
2dcb0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
2dcc0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
2dcd0 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
2dce0 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
2dcf0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
2dd00 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
2dd10 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
2dd20 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
2dd30 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
2dd40 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
2dd50 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
2dd60 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
2dd70 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
2dd80 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
2dd90 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
2dda0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
2ddb0 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
2ddc0 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
2ddd0 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
2dde0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
2ddf0 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
2de00 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
2de10 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
2de20 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
2de30 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2de40 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2de50 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2de60 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
2de70 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
2de80 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
2de90 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
2dea0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2deb0 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
2dec0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
2ded0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2dee0 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2def0 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
2df00 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2df10 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
2df20 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
2df30 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
2df40 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
2df50 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
2df60 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
2df70 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2df80 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2df90 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2dfa0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
2dfb0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2dfc0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2dfd0 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
2dfe0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2dff0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2e000 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2e010 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
2e020 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2e030 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2e040 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2e050 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2e060 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2e070 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2e080 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2e090 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2e0a0 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
2e0b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2e0c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2e0d0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2e0e0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2e0f0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2e100 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2e110 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2e120 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
2e130 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
2e140 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2e150 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e160 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
2e170 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
2e180 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  sult.**.** ^(The
2e190 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2e1a0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2e1b0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
2e1c0 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
2e1d0 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
2e1e0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
2e1f0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2e200 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
2e210 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
2e220 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
2e230 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
2e240 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
2e250 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
2e260 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
2e270 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
2e280 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
2e290 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
2e2a0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2e2b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2e2c0 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
2e2d0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2e2e0 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
2e2f0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2e300 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
2e310 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2e320 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
2e330 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
2e340 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
2e350 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
2e360 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
2e370 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
2e380 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
2e390 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
2e3a0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
2e3b0 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
2e3c0 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
2e3d0 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
2e3e0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
2e3f0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
2e400 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
2e410 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
2e420 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
2e430 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
2e440 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
2e450 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
2e460 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
2e470 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
2e480 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
2e490 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
2e4a0 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
2e4b0 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
2e4c0 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
2e4d0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
2e4e0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
2e4f0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
2e500 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
2e510 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
2e520 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2e530 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
2e540 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
2e550 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
2e560 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
2e570 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
2e580 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
2e590 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
2e5a0 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
2e5b0 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
2e5c0 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
2e5d0 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
2e5e0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2e5f0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2e600 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
2e610 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2e620 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2e630 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2e640 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2e650 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2e660 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2e670 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
2e680 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
2e690 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  nt.**.** After a
2e6a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e6b0 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
2e6c0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
2e6d0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
2e6e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2e6f0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2e700 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
2e710 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
2e720 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
2e730 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2e740 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2e750 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
2e760 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
2e770 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
2e780 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
2e790 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
2e7a0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
2e7b0 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
2e7c0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
2e7d0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2e7e0 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
2e7f0 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
2e800 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
2e810 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
2e820 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
2e830 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
2e840 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2e850 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2e860 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2e870 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
2e880 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2e890 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
2e8a0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2e8b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
2e8c0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
2e8d0 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
2e8e0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2e8f0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
2e900 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
2e910 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2e920 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
2e930 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
2e940 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
2e950 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2e960 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
2e970 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
2e980 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
2e990 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
2e9a0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
2e9b0 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
2e9c0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
2e9d0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
2e9e0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2e9f0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
2ea00 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
2ea10 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
2ea20 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
2ea30 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
2ea40 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
2ea50 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
2ea60 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
2ea70 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
2ea80 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
2ea90 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
2eaa0 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
2eab0 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
2eac0 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
2ead0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
2eae0 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
2eaf0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
2eb00 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
2eb10 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
2eb20 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
2eb30 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
2eb40 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2eb50 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
2eb60 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
2eb70 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
2eb80 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
2eb90 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
2eba0 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
2ebb0 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
2ebc0 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
2ebd0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
2ebe0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
2ebf0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
2ec00 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
2ec10 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
2ec20 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
2ec30 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
2ec40 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
2ec50 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
2ec60 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
2ec70 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
2ec80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2ec90 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
2eca0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2ecb0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
2ecc0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
2ecd0 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
2ece0 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
2ecf0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
2ed00 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
2ed10 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
2ed20 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
2ed30 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
2ed40 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
2ed50 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
2ed60 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
2ed70 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
2ed80 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
2ed90 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
2eda0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
2edb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2edc0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
2edd0 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
2ede0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
2edf0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
2ee00 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
2ee10 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
2ee20 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
2ee30 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
2ee40 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
2ee50 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
2ee60 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2ee70 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2ee80 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
2ee90 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
2eea0 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
2eeb0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2eec0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
2eed0 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
2eee0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
2eef0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
2ef00 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
2ef10 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
2ef20 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
2ef30 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
2ef40 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
2ef50 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
2ef60 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
2ef70 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2ef80 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2ef90 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
2efa0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
2efb0 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
2efc0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
2efd0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
2efe0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
2eff0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
2f000 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
2f010 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
2f020 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
2f030 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
2f040 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
2f050 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
2f060 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
2f070 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
2f080 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f090 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
2f0a0 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
2f0b0 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2f0c0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
2f0d0 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
2f0e0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
2f0f0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
2f100 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
2f110 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
2f120 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
2f130 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
2f140 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f150 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
2f160 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
2f170 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
2f180 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
2f190 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
2f1a0 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
2f1b0 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
2f1c0 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
2f1d0 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
2f1e0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2f1f0 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
2f200 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
2f210 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
2f220 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
2f230 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2f240 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
2f250 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
2f260 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
2f270 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
2f280 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
2f290 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f2a0 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
2f2b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
2f2c0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
2f2d0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2f2e0 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
2f2f0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2f300 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73    But after vers
2f310 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71  ion 3.6.23.1, sq
2f320 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67  lite3_step() beg
2f330 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73  an.** calling [s
2f340 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2f350 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
2f360 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e   this circumstan
2f370 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61  ce rather.** tha
2f380 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
2f390 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68  ITE_MISUSE].  Th
2f3a0 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64  is is not consid
2f3b0 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69  ered a compatibi
2f3c0 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65  lity.** break be
2f3d0 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63  cause any applic
2f3e0 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20  ation that ever 
2f3f0 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49  receives an SQLI
2f400 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a  TE_MISUSE error.
2f410 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20  ** is broken by 
2f420 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65  definition.  The
2f430 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
2f440 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65  TORESET] compile
2f450 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  -time option.** 
2f460 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
2f470 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63  estore the legac
2f480 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  y behavior..**.*
2f490 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
2f4a0 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
2f4b0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
2f4c0 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
2f4d0 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
2f4e0 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
2f4f0 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
2f500 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
2f510 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
2f520 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
2f530 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2f540 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
2f550 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
2f560 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
2f570 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2f580 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2f590 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
2f5a0 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
2f5b0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
2f5c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
2f5d0 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
2f5e0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
2f5f0 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
2f600 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
2f610 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
2f620 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
2f630 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
2f640 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
2f650 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
2f660 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
2f670 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
2f680 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
2f690 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2f6a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2f6b0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
2f6c0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
2f6d0 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
2f6e0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
2f6f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2f700 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
2f710 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
2f720 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
2f730 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
2f740 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
2f750 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
2f760 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
2f770 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
2f780 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2f790 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ded..*/.SQLITE_A
2f7a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
2f7b0 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
2f7c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2f7d0 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
2f7e0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
2f7f0 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt set.**.** ^Th
2f800 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2f810 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
2f820 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2f830 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2f840 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
2f850 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2f860 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
2f870 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f880 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
2f890 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
2f8a0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
2f8b0 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
2f8c0 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
2f8d0 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
2f8e0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
2f8f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
2f900 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
2f910 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
2f920 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2f930 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
2f940 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2f950 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2f960 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
2f970 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
2f980 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
2f990 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2f9a0 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
2f9b0 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
2f9c0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2f9d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2f9e0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
2f9f0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
2fa00 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2fa10 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
2fa20 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
2fa30 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
2fa40 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2fa50 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
2fa60 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
2fa70 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
2fa80 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
2fa90 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
2faa0 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
2fab0 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
2fac0 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
2fad0 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
2fae0 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
2faf0 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
2fb00 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
2fb10 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2fb20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2fb30 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49  count()].*/.SQLI
2fb40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2fb50 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
2fb60 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2fb70 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2fb80 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
2fb90 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
2fba0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
2fbb0 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
2fbc0 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
2fbd0 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
2fbe0 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
2fbf0 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
2fc00 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
2fc10 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2fc20 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
2fc30 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
2fc40 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
2fc50 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
2fc60 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
2fc70 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
2fc80 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2fc90 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
2fca0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
2fcb0 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
2fcc0 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
2fcd0 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
2fce0 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
2fcf0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
2fd00 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
2fd10 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
2fd20 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
2fd30 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
2fd40 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
2fd50 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2fd60 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
2fd70 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
2fd80 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
2fd90 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
2fda0 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
2fdb0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
2fdc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
2fdd0 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
2fde0 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
2fdf0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
2fe00 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
2fe10 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
2fe20 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
2fe30 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
2fe40 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
2fe50 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
2fe60 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
2fe70 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
2fe80 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
2fe90 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
2fea0 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
2feb0 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
2fec0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
2fed0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2fee0 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
2fef0 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e   set" interface.
2ff00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2ff10 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
2ff20 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2ff30 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
2ff40 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
2ff50 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
2ff60 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
2ff70 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
2ff80 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
2ff90 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
2ffa0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ffb0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
2ffc0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
2ffd0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2ffe0 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
2fff0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
30000 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
30010 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
30020 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
30030 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
30040 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
30050 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
30060 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
30070 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
30080 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
30090 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
300a0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
300b0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
300c0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
300d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
300e0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
300f0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
30100 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
30110 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
30120 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
30130 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
30140 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
30150 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
30160 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
30170 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
30180 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
30190 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
301a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
301b0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
301c0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
301d0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
301e0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
301f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
30200 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
30210 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
30220 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
30230 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
30240 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
30250 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
30260 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
30270 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
30280 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
30290 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
302a0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
302b0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
302c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
302d0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
302e0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
302f0 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
30300 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
30310 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
30320 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
30330 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
30340 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
30350 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
30360 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
30370 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
30380 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
30390 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
303a0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
303b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
303c0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
303d0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
303e0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
303f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30400 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
30410 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
30420 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
30430 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
30440 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
30450 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
30460 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
30470 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
30480 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
30490 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
304a0 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
304b0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
304c0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
304d0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
304e0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
304f0 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
30500 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
30510 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
30520 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
30530 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
30540 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
30550 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
30560 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
30570 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
30580 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
30590 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
305a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
305b0 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
305c0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
305d0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
305e0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
305f0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
30600 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
30610 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
30620 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
30630 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
30640 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
30650 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
30660 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
30670 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30680 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
30690 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
306a0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
306b0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
306c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
306d0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
306e0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
306f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30700 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
30710 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
30720 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
30730 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
30740 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
30750 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
30760 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
30770 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
30780 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
30790 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
307a0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
307b0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
307c0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
307d0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
307e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
307f0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
30800 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
30810 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
30820 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
30830 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
30840 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
30850 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
30860 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
30870 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
30880 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30890 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
308a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
308b0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
308c0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
308d0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
308e0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
308f0 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
30900 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
30910 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
30920 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
30930 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
30940 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
30950 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
30960 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
30970 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
30980 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
30990 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
309a0 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
309b0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
309c0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
309d0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
309e0 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
309f0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
30a00 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
30a10 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
30a20 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
30a30 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
30a40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30a50 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
30a60 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
30a70 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
30a80 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
30a90 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
30aa0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
30ab0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
30ac0 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
30ad0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
30ae0 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
30af0 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
30b00 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
30b10 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
30b20 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
30b30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
30b40 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
30b50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
30b60 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
30b70 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
30b80 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
30b90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
30ba0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
30bb0 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
30bc0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
30bd0 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
30be0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30bf0 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
30c00 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
30c10 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
30c20 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
30c30 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
30c40 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
30c50 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
30c60 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
30c70 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
30c80 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
30c90 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
30ca0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
30cb0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
30cc0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
30cd0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30ce0 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
30cf0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30d00 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
30d10 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
30d20 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
30d30 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
30d40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
30d50 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
30d60 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
30d70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30d80 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
30d90 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
30da0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
30db0 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
30dc0 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
30dd0 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
30de0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
30df0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
30e00 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
30e10 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
30e20 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
30e30 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
30e40 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
30e50 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
30e60 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
30e70 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
30e80 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
30e90 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
30ea0 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
30eb0 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
30ec0 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
30ed0 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
30ee0 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
30ef0 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
30f00 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
30f10 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
30f20 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
30f30 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
30f40 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
30f50 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
30f60 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
30f70 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
30f80 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
30f90 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
30fa0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
30fb0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
30fc0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
30fd0 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
30fe0 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
30ff0 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
31000 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
31010 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
31020 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
31030 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
31040 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
31050 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
31060 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
31070 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
31080 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
31090 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
310a0 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
310b0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
310c0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
310d0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
310e0 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
310f0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
31100 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
31110 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
31120 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
31130 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
31140 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
31150 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
31160 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
31170 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
31180 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
31190 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
311a0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
311b0 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
311c0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
311d0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
311e0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
311f0 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
31200 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  R.** <tr><td>  F
31210 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
31220 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
31230 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
31240 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
31250 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
31260 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
31270 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a   [CAST] to BLOB.
31280 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
31290 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
312a0 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
312b0 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
312c0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
312d0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
312e0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
312f0 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
31300 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
31310 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
31320 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
31330 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
31340 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
31350 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
31360 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
31370 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
31380 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
31390 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
313a0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
313b0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
313c0 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
313d0 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
313e0 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
313f0 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
31400 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
31410 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66   above makes ref
31420 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61  erence to standa
31430 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e  rd C library fun
31440 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a  ctions atoi().**
31450 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51   and atof().  SQ
31460 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65  Lite does not re
31470 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66  ally use these f
31480 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61  unctions.  It ha
31490 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75  s its.** own equ
314a0 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  ivalent internal
314b0 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
314c0 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
314d0 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
314e0 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
314f0 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
31500 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
31510 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
31520 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
31530 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
31540 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
31550 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
31560 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
31570 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
31580 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
31590 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
315a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
315b0 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
315c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
315d0 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
315e0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
315f0 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
31600 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
31610 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
31620 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
31630 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
31640 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
31650 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
31660 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
31670 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
31680 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
31690 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
316a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
316b0 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
316c0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
316d0 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
316e0 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
316f0 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
31700 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
31710 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
31720 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
31730 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31740 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
31750 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
31760 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
31770 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
31780 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
31790 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
317a0 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
317b0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
317c0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
317d0 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
317e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
317f0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
31800 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
31810 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
31820 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
31830 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
31840 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
31850 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
31860 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73  .** ^Conversions
31870 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
31880 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
31890 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
318a0 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
318b0 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
318c0 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
318d0 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
318e0 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
318f0 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
31900 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
31910 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65  ointer reference
31920 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  s will have been
31930 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
31940 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
31950 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
31960 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
31970 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
31980 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68  but sometimes th
31990 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f  ey.** are not po
319a0 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68  ssible and in th
319b0 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20  ose cases prior 
319c0 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76  pointers are inv
319d0 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  alidated..**.** 
319e0 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65  The safest and e
319f0 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62  asiest to rememb
31a00 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  er policy is to 
31a10 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
31a20 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
31a30 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
31a40 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
31a50 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
31a60 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
31a70 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
31a80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31a90 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
31aa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31ab0 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
31ac0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
31ad0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
31ae0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
31af0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
31b00 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
31b10 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
31b20 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
31b30 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
31b40 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
31b50 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
31b60 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
31b70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31b80 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
31b90 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
31ba0 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
31bb0 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
31bc0 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
31bd0 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
31be0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
31bf0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
31c00 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
31c10 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
31c20 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
31c30 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
31c40 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
31c50 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
31c60 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
31c70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
31c80 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
31c90 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
31ca0 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
31cb0 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
31cc0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
31cd0 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
31ce0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
31cf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31d00 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  es()..**.** ^The
31d10 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
31d20 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
31d30 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
31d40 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
31d50 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
31d60 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
31d70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
31d80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
31d90 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
31da0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
31db0 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65  called.  ^The me
31dc0 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
31dd0 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
31de0 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
31df0 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
31e00 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
31e10 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
31e20 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
31e30 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
31e40 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
31e50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
31e60 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
31e70 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
31e80 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
31e90 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
31ea0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
31eb0 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
31ec0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
31ed0 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
31ee0 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
31ef0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
31f00 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
31f10 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
31f20 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
31f30 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
31f40 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
31f50 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
31f60 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
31f70 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
31f80 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
31f90 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
31fa0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
31fb0 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ^.*/.SQLITE_API 
31fc0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
31fd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
31fe0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31ff0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
32000 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
32010 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
32020 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
32030 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
32040 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
32050 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
32060 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
32070 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
32080 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  PI double sqlite
32090 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
320a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
320b0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
320c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
320d0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
320e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
320f0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
32100 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
32110 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
32120 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
32130 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
32140 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75  LITE_API const u
32150 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
32160 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32170 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
32180 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
32190 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
321a0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
321b0 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
321c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
321d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
321e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
321f0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
32200 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
32210 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
32220 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
32230 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
32240 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
32250 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
32260 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
32270 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
32280 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
32290 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
322a0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
322b0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
322c0 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
322d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
322e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
322f0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
32300 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
32310 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
32320 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20  no errors.** or 
32330 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
32340 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65   is never been e
32350 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73  valuated, then s
32360 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
32370 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c  ) returns.** SQL
32380 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65  ITE_OK.  ^If the
32390 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
323a0 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65  luation of state
323b0 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74  ment S failed, t
323c0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  hen.** sqlite3_f
323d0 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72  inalize(S) retur
323e0 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ns the appropria
323f0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
32400 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
32410 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
32420 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32430 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74  finalize(S) rout
32440 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
32450 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
32460 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66  uring.** the lif
32470 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70  e cycle of [prep
32480 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
32490 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61  S:.** before sta
324a0 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72  tement S is ever
324b0 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65   evaluated, afte
324c0 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
324d0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
324e0 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20  e3_reset()], or 
324f0 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a  after any call.*
32500 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  * to [sqlite3_st
32510 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73  ep()] regardless
32520 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
32530 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ot the statement
32540 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   has.** complete
32550 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a  d execution..**.
32560 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c  ** ^Invoking sql
32570 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
32580 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  on a NULL pointe
32590 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
325a0 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  no-op..**.** The
325b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
325c0 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79  t finalize every
325d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
325e0 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74  ment] in order t
325f0 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75  o avoid.** resou
32600 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69  rce leaks.  It i
32610 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72  s a grievous err
32620 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
32630 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f  cation to try to
32640 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72   use.** a prepar
32650 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ed statement aft
32660 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
32670 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75  inalized.  Any u
32680 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  se of a prepared
32690 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66  .** statement af
326a0 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
326b0 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65  finalized can re
326c0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
326d0 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72  d and.** undesir
326e0 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75  able behavior su
326f0 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20  ch as segfaults 
32700 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74  and heap corrupt
32710 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
32720 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  PI int sqlite3_f
32730 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
32740 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
32750 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
32760 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
32770 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
32780 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
32790 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
327a0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
327b0 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
327c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
327d0 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
327e0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
327f0 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
32800 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
32810 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
32820 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
32830 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
32840 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
32850 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
32860 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
32870 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
32880 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
32890 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
328a0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
328b0 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
328c0 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
328d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
328e0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
328f0 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
32900 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
32910 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
32920 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
32930 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
32940 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
32950 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
32960 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
32970 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
32980 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
32990 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
329a0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
329b0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
329c0 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
329d0 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
329e0 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
329f0 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
32a00 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
32a10 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
32a20 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
32a30 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
32a40 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
32a50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
32a60 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
32a70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
32a80 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
32a90 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
32aa0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
32ab0 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
32ac0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
32ad0 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
32ae0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
32af0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
32b00 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
32b10 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
32b20 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
32b30 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
32b40 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
32b50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
32b60 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
32b70 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
32b80 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
32b90 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
32ba0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
32bb0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
32bc0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
32bd0 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
32be0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
32bf0 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
32c00 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
32c10 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
32c20 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
32c30 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
32c40 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
32c50 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
32c60 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
32c70 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
32c80 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
32c90 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
32ca0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
32cb0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
32cc0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
32cd0 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
32ce0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
32cf0 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
32d00 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
32d10 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
32d20 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
32d30 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
32d40 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
32d50 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
32d60 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
32d70 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
32d80 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
32d90 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
32da0 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
32db0 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
32dc0 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
32dd0 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
32de0 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
32df0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
32e00 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
32e10 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
32e20 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
32e30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32e40 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
32e50 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
32e60 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
32e70 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
32e80 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
32e90 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
32ea0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
32eb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32ec0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
32ed0 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
32ee0 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
32ef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
32f00 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
32f10 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
32f20 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
32f30 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
32f40 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
32f50 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
32f60 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
32f70 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
32f80 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
32f90 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
32fa0 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
32fb0 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
32fc0 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
32fd0 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
32fe0 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
32ff0 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
33000 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
33010 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
33020 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
33030 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
33040 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
33050 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
33060 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
33070 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
33080 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
33090 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
330a0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
330b0 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
330c0 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
330d0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
330e0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
330f0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
33100 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
33110 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
33120 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
33130 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
33140 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
33150 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
33160 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
33170 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
33180 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
33190 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
331a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
331b0 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
331c0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
331d0 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
331e0 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
331f0 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
33200 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
33210 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
33220 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
33230 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
33240 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
33250 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
33260 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
33270 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
33280 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
33290 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
332a0 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63  ers.  The applic
332b0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74  ation should set
332c0 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
332d0 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  to.** [SQLITE_UT
332e0 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75  F16LE] if the fu
332f0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
33300 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a  ation invokes .*
33310 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
33320 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20  _text16le()] on 
33330 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51  an input, or [SQ
33340 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66  LITE_UTF16BE] if
33350 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
33360 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b  tation invokes [
33370 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33380 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16be()] on an 
33390 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51  input, or.** [SQ
333a0 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b  LITE_UTF16] if [
333b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
333c0 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  xt16()] is used,
333d0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   or [SQLITE_UTF8
333e0 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20  ].** otherwise. 
333f0 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66   ^The same SQL f
33400 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
33410 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
33420 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a  le times using.*
33430 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66  * different pref
33440 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
33450 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65  ings, with diffe
33460 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
33470 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ions for.** each
33480 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57   encoding..** ^W
33490 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
334a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
334b0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
334c0 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
334d0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
334e0 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
334f0 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
33500 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
33510 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
33520 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
33530 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  h parameter may 
33540 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52  optionally be OR
33550 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
33560 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a  DETERMINISTIC].*
33570 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74  * to signal that
33580 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
33590 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
335a0 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74   the same result
335b0 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61   given.** the sa
335c0 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e  me inputs within
335d0 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
335e0 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53  atement.  Most S
335f0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  QL functions are
33600 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69  .** deterministi
33610 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e  c.  The built-in
33620 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20   [random()] SQL 
33630 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65  function is an e
33640 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66  xample of a.** f
33650 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  unction that is 
33660 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69  not deterministi
33670 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71  c.  The SQLite q
33680 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20  uery planner is 
33690 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f  able to.** perfo
336a0 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70  rm additional op
336b0 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64  timizations on d
336c0 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e  eterministic fun
336d0 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a  ctions, so use.*
336e0 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
336f0 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20  _DETERMINISTIC] 
33700 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e  flag is recommen
33710 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62  ded where possib
33720 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  le..**.** ^(The 
33730 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
33740 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
33750 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
33760 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
33770 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
33780 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
33790 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
337a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
337b0 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
337c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
337d0 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
337e0 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
337f0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
33800 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
33810 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
33820 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
33830 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
33840 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
33850 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
33860 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
33870 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
33880 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
33890 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
338a0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
338b0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
338c0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
338d0 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
338e0 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
338f0 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
33900 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
33910 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
33920 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
33930 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
33940 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
33950 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
33960 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
33970 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
33980 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
33990 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
339a0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
339b0 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
339c0 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
339d0 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
339e0 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
339f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
33a00 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33a10 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
33a20 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
33a30 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
33a40 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
33a50 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
33a60 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
33a70 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
33a80 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
33a90 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
33aa0 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
33ab0 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
33ac0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
33ad0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
33ae0 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
33af0 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
33b00 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
33b10 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
33b20 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33b30 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
33b40 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
33b50 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
33b60 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
33b70 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
33b80 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
33b90 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
33ba0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
33bb0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
33bc0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
33bd0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
33be0 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
33bf0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
33c00 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
33c10 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
33c20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
33c30 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
33c40 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
33c50 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
33c60 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
33c70 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
33c80 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
33c90 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
33ca0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
33cb0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
33cc0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
33cd0 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
33ce0 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
33cf0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
33d00 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
33d10 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
33d20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
33d30 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
33d40 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
33d50 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
33d60 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
33d70 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
33d80 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
33d90 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
33da0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
33db0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
33dc0 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
33dd0 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
33de0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
33df0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
33e00 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
33e10 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
33e20 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
33e30 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
33e40 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
33e50 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
33e60 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
33e70 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
33e80 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
33e90 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
33ea0 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
33eb0 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
33ec0 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
33ed0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
33ee0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
33ef0 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
33f00 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
33f10 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
33f20 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
33f30 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
33f40 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
33f50 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33f60 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
33f70 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
33f80 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33f90 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
33fa0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
33fb0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
33fc0 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
33fd0 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
33fe0 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
33ff0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34000 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
34010 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
34020 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
34030 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
34040 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
34050 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
34060 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34070 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
34080 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
34090 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
340a0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
340b0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
340c0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
340d0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
340e0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
340f0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
34100 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
34110 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
34120 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
34130 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
34140 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
34150 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
34160 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54  ntext*).);.SQLIT
34170 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
34180 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34190 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
341a0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
341b0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
341c0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
341d0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
341e0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
341f0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
34200 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
34210 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
34220 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
34230 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
34240 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
34250 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
34260 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
34270 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53  3_context*).);.S
34280 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
34290 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
342a0 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
342b0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
342c0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
342d0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
342e0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
342f0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
34300 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
34310 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34320 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
34330 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
34340 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
34350 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
34360 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
34370 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
34380 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
34390 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
343a0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
343b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
343c0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
343d0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
343e0 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
343f0 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
34400 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
34410 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
34420 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
34430 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
34440 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
34450 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20 20             1    
34460 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d  /* IMP: R-37514-
34470 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65  35566 */.#define
34480 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
34490 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49         2    /* I
344a0 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33  MP: R-03371-3763
344b0 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  7 */.#define SQL
344c0 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
344d0 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20     3    /* IMP: 
344e0 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f  R-51971-34154 */
344f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
34500 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
34510 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
34520 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
34530 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
34540 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
34550 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64     /* Deprecated
34560 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
34570 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
34580 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
34590 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
345a0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
345b0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
345c0 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  tion Flags.**.**
345d0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
345e0 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67   may be ORed tog
345f0 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a  ether with the .
34600 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
34610 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  | preferred text
34620 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68   encoding] as th
34630 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
34640 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  t.** to [sqlite3
34650 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
34660 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
34670 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
34680 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
34690 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
346a0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65  on_v2()]..*/.#de
346b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45  fine SQLITE_DETE
346c0 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38  RMINISTIC    0x8
346d0 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
346e0 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
346f0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
34700 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
34710 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
34720 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
34730 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
34740 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
34750 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
34760 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
34770 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
34780 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
34790 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
347a0 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
347b0 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
347c0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
347d0 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
347e0 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
347f0 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
34800 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
34810 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
34820 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
34830 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
34840 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
34850 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
34860 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
34870 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
34880 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
34890 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
348a0 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
348b0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
348c0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
348d0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
348e0 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
348f0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
34900 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
34910 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
34920 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
34930 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
34940 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
34950 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
34960 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
34970 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
34980 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
34990 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
349a0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
349b0 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
349c0 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
349d0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
349e0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
349f0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
34a00 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
34a10 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
34a20 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20  3_int64,int),.  
34a30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34a40 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65      void*,sqlite
34a50 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
34a60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34a70 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
34a80 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74  Function Paramet
34a90 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20  er Values.**.** 
34aa0 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
34ab0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
34ac0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
34ad0 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
34ae0 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
34af0 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
34b00 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
34b10 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
34b20 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
34b30 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
34b40 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ate..**.** The x
34b50 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
34b60 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
34b70 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
34b80 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
34b90 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
34ba0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
34bb0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34bc0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
34bd0 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
34be0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
34bf0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
34c00 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
34c10 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
34c20 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
34c30 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
34c40 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
34c50 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
34c60 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
34c70 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
34c80 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
34c90 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34ca0 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
34cb0 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
34cc0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
34cd0 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
34ce0 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
34cf0 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
34d00 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
34d10 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
34d20 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
34d30 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
34d40 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
34d50 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34d60 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
34d70 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
34d80 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
34d90 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
34da0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34db0 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
34dc0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
34dd0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
34de0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
34df0 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
34e00 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
34e10 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
34e20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
34e30 63 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20  cept that these 
34e40 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
34e50 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
34e60 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34e70 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
34e80 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
34e90 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
34ea0 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
34eb0 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
34ec0 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
34ed0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
34ee0 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
34ef0 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
34f00 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
34f10 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
34f20 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
34f30 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
34f40 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
34f50 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
34f60 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
34f70 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
34f80 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
34f90 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
34fa0 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
34fb0 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
34fc0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
34fd0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
34fe0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
34ff0 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
35000 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
35010 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
35020 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
35030 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
35040 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
35050 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
35060 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
35070 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
35080 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
35090 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
350a0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
350b0 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
350c0 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
350d0 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
350e0 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
350f0 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
35100 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
35110 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
35120 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
35130 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
35140 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
35150 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
35160 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
35170 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
35180 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
35190 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
351a0 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
351b0 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
351c0 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
351d0 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
351e0 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
351f0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
35200 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
35210 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
35220 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
35230 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
35240 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
35250 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
35260 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
35270 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
35280 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
35290 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
352a0 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
352b0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
352c0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
352d0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
352e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
352f0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
35300 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
35310 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
35320 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
35330 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
35340 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
35350 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
35360 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
35370 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
35380 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
35390 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
353a0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
353b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
353c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
353d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
353e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
353f0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
35400 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
35410 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  I double sqlite3
35420 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
35430 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
35440 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
35450 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
35460 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
35470 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
35480 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
35490 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
354a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
354b0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
354c0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
354d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
354e0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
354f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
35500 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
35510 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
35520 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
35530 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
35540 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
35550 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
35560 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
35570 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
35580 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
35590 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
355a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
355b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
355c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
355d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
355e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
355f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
35600 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
35610 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
35620 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
35630 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
35640 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
35650 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74  *.** Implementat
35660 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74  ions of aggregat
35670 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
35680 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74  use this.** rout
35690 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ine to allocate 
356a0 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69  memory for stori
356b0 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
356c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
356d0 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
356e0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
356f0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
35700 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66   is called .** f
35710 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
35720 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
35730 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c  on, SQLite.** al
35740 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d  locates N of mem
35750 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
35760 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
35770 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
35780 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77  er.** to the new
35790 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63   memory. ^On sec
357a0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
357b0 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
357c0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
357d0 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
357e0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
357f0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
35800 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  nce,.** the same
35810 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
35820 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67  ned.  Sqlite3_ag
35830 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
35840 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a  ) is normally.**
35850 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72   called once for
35860 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
35870 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61   of the xStep ca
35880 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20  llback and then 
35890 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65  one.** last time
358a0 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c   when the xFinal
358b0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
358c0 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f  oked.  ^(When no
358d0 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61   rows match.** a
358e0 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  n aggregate quer
358f0 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63  y, the xStep() c
35900 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61  allback of the a
35910 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
35920 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
35930 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c  ion is never cal
35940 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29  led and xFinal()
35950 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74   is called exact
35960 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74  ly once..** In t
35970 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69  hose cases, sqli
35980 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
35990 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65  ntext() might be
359a0 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
359b0 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72  ** first time fr
359c0 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c  om within xFinal
359d0 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
359e0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
359f0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
35a00 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
35a10 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a  a NULL pointer .
35a20 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61  ** when first ca
35a30 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73  lled if N is les
35a40 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
35a50 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
35a60 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
35a70 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  te error occurs.
35a80 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f  .**.** ^(The amo
35a90 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c  unt of space all
35aa0 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
35ab0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
35ac0 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64  ext(C,N) is.** d
35ad0 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
35ae0 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20   N parameter on 
35af0 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c  first successful
35b00 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67   call.  Changing
35b10 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
35b20 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74   N in subsequent
35b30 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
35b40 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
35b50 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74  xt() within.** t
35b60 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
35b70 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
35b80 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73  nce will not res
35b90 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ize the memory.*
35ba0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20  * allocation.)^ 
35bb0 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e   Within the xFin
35bc0 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20  al callback, it 
35bd0 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20  is customary to 
35be0 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61  set.** N=0 in ca
35bf0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  lls to sqlite3_a
35c00 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
35c10 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f  (C,N) so that no
35c20 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d   .** pointless m
35c30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
35c40 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e  s occur..**.** ^
35c50 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
35c60 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d  ally frees the m
35c70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
35c80 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61  by .** sqlite3_a
35c90 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
35ca0 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  () when the aggr
35cb0 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63  egate query conc
35cc0 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
35cd0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
35ce0 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20   must be a copy 
35cf0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
35d00 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
35d10 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
35d20 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
35d30 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
35d40 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f  * to the xStep o
35d50 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
35d60 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
35d70 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
35d80 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
35d90 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
35da0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
35db0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
35dc0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
35dd0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
35de0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
35df0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
35e00 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
35e10 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
35e20 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
35e30 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
35e40 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
35e50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
35e60 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
35e70 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
35e80 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
35e90 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
35ea0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
35eb0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
35ec0 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
35ed0 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
35ee0 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
35ef0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
35f00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35f10 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
35f20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
35f30 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
35f40 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
35f50 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
35f60 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
35f70 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
35f80 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
35f90 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
35fa0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
35fb0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
35fc0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
35fd0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35fe0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
35ff0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
36000 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
36010 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
36020 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
36030 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36040 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
36050 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
36060 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
36070 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
36080 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
36090 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
360a0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
360b0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
360c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
360d0 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
360e0 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
360f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36100 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
36110 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
36120 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
36130 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
36140 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
36150 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
36160 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
36170 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51   function..*/.SQ
36180 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
36190 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
361a0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
361b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
361c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
361d0 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
361e0 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68  ry Data.**.** Th
361f0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  ese functions ma
36200 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f  y be used by (no
36210 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c  n-aggregate) SQL
36220 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
36230 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
36240 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
36250 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
36260 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
36270 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
36280 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
36290 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
362a0 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
362b0 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
362c0 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
362d0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
362e0 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
362f0 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
36300 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d  served.  An exam
36310 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20  ple.** of where 
36320 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73  this might be us
36330 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67  eful is in a reg
36340 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
36350 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63  matching.** func
36360 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
36370 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
36380 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
36390 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72  sion can be stor
363a0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
363b0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
363c0 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74  h the pattern st
363d0 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20  ring.  .** Then 
363e0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70  as long as the p
363f0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65  attern string re
36400 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a  mains the same,.
36410 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  ** the compiled 
36420 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
36430 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
36440 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
36450 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
36460 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
36470 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36480 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
36490 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
364a0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
364b0 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
364c0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
364d0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
364e0 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
364f0 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
36500 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
36510 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
36520 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36530 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65  ction. ^If there
36540 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a   is no metadata.
36550 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
36560 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  th the function 
36570 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73  argument, this s
36580 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
36590 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ta() interface.*
365a0 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  * returns a NULL
365b0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
365c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ^The sqlite3_set
365d0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
365e0 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
365f0 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20  s P as metadata 
36600 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
36610 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
36620 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36630 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  ned function.  ^
36640 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
36650 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
36660 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20  et_auxdata(C,N) 
36670 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68  return P from th
36680 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
36690 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
366a0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61  data(C,N,P,X) ca
366b0 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61  ll if the metada
366c0 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69  ta is still vali
366d0 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20  d or.** NULL if 
366e0 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73  the metadata has
366f0 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e   been discarded.
36700 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20  .** ^After each 
36710 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
36720 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
36730 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20  P,X) where X is 
36740 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c  not NULL,.** SQL
36750 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
36760 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  the destructor f
36770 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70  unction X with p
36780 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74  arameter P exact
36790 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e  ly.** once, when
367a0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
367b0 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53   discarded..** S
367c0 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
367d0 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74   discard the met
367e0 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d  adata at any tim
367f0 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75  e, including: <u
36800 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  l>.** <li> when 
36810 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
36820 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
36830 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72  eter changes, or
36840 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73  .** <li> when [s
36850 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
36860 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
36870 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
36880 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  d for the.**    
36890 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c    SQL statement,
368a0 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e   or.** <li> when
368b0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
368c0 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65  data() is invoke
368d0 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73  d again on the s
368e0 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f  ame parameter, o
368f0 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67  r.** <li> during
36900 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71   the original sq
36910 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
36920 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20  a() call when a 
36930 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20  memory .**      
36940 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
36950 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e   occurs. </ul>)^
36960 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20  .**.** Note the 
36970 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70  last bullet in p
36980 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20  articular.  The 
36990 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20  destructor X in 
369a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
369b0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
369c0 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
369d0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
369e0 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69  fore the.** sqli
369f0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
36a00 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e  ) interface even
36a10 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65   returns.  Hence
36a20 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
36a30 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64  data().** should
36a40 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20   be called near 
36a50 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
36a60 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
36a70 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a  tation and the.*
36a80 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  * function imple
36a90 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
36aa0 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73   not make any us
36ab0 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20  e of P after.** 
36ac0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
36ad0 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63  ata() has been c
36ae0 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  alled..**.** ^(I
36af0 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
36b00 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
36b10 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
36b20 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
36b30 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
36b40 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d  ers that are com
36b50 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61  pile-time consta
36b60 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c  nts, including l
36b70 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
36b80 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
36b90 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e  ] and expression
36ba0 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20  s composed from 
36bb0 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a  the same.)^.**.*
36bc0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
36bd0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
36be0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
36bf0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
36c00 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
36c10 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
36c20 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
36c30 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
36c40 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
36c50 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
36c60 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
36c70 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
36c80 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
36c90 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
36ca0 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
36cb0 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
36cc0 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
36cd0 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
36ce0 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
36cf0 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65  havior.**.** The
36d00 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
36d10 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
36d20 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
36d30 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
36d40 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
36d50 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
36d60 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
36d70 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e  sult_blob()].  ^
36d80 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
36d90 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
36da0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
36db0 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
36dc0 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
36dd0 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
36de0 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
36df0 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
36e00 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
36e10 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65  destroyed.  ^The
36e20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
36e30 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
36e40 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
36e50 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
36e60 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
36e70 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
36e80 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
36e90 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
36ea0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
36eb0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
36ec0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
36ed0 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
36ee0 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
36ef0 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
36f00 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
36f10 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
36f20 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  rs..*/.typedef v
36f30 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
36f40 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
36f50 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
36f60 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
36f70 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
36f80 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
36f90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
36fa0 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
36fb0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
36fc0 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
36fd0 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
36fe0 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
36ff0 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a  n SQL Function.*
37000 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
37010 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
37020 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
37030 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
37040 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
37050 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
37060 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
37070 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
37080 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
37090 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
370a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
370b0 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
370c0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
370d0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
370e0 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
370f0 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
37100 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
37110 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
37120 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
37130 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
37140 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
37150 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
37160 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
37170 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
37180 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
37190 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
371a0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
371b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
371c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
371d0 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
371e0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
371f0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
37200 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37210 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
37220 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
37230 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
37240 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
37250 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
37260 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
37270 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
37280 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
37290 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
372a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
372b0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  sult_zeroblob() 
372c0 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74  interfaces set t
372d0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
372e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
372f0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
37300 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f   to be a BLOB co
37310 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72  ntaining all zer
37320 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e  o.** bytes and N
37330 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20   bytes in size, 
37340 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
37350 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20  alue of the 2nd 
37360 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
37370 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
37380 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
37390 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
373a0 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
373b0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
373c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
373d0 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
373e0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
373f0 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
37400 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
37410 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37420 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
37430 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
37440 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
37450 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
37460 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
37470 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
37480 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
37490 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ion..** ^SQLite 
374a0 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
374b0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
374c0 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
374d0 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
374e0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
374f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37500 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
37510 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
37520 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53  ror message.  ^S
37530 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
37540 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
37550 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f  ssage string fro
37560 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
37570 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d  _error() as UTF-
37580 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  8. ^SQLite.** in
37590 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72  terprets the str
375a0 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
375b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
375c0 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  ) as UTF-16 in n
375d0 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
375e0 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68  der.  ^If the th
375f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
37600 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37610 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
37620 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37630 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
37640 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
37650 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
37660 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
37670 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
37680 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
37690 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
376a0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
376b0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
376c0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
376d0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
376e0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
376f0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
37700 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
37710 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
37720 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
37730 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
37740 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
37750 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
37760 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
37770 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
37780 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
37790 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
377a0 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
377b0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
377c0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
377d0 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a  ge text before.*
377e0 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20  * they return.  
377f0 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69  Hence, the calli
37800 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ng function can 
37810 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a  deallocate or.**
37820 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74   modify the text
37830 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75   after they retu
37840 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  rn without harm.
37850 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37860 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
37870 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68  de() function ch
37880 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20  anges the error 
37890 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  code.** returned
378a0 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20   by SQLite as a 
378b0 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72  result of an err
378c0 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e  or in a function
378d0 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a  .  ^By default,.
378e0 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
378f0 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
37900 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e  R.  ^A subsequen
37910 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
37920 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
37930 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
37940 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
37950 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  resets the error
37960 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f   code to SQLITE_
37970 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ERROR..**.** ^Th
37980 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37990 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20  _error_toobig() 
379a0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
379b0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
379c0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
379d0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
379e0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
379f0 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70   too long to rep
37a00 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  resent..**.** ^T
37a10 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37a20 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20  t_error_nomem() 
37a30 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
37a40 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
37a50 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
37a60 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
37a70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
37a80 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
37a90 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37aa0 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
37ab0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
37ac0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
37ad0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
37ae0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
37af0 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
37b00 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
37b10 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
37b20 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
37b30 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
37b40 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
37b50 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
37b60 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
37b70 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
37b80 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37b90 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
37ba0 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
37bb0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
37bc0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
37bd0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
37be0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37bf0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
37c00 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
37c10 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
37c20 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
37c30 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
37c40 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
37c50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37c60 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
37c70 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
37c80 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
37c90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37ca0 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
37cb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37cc0 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
37cd0 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
37ce0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
37cf0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
37d00 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
37d10 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
37d20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
37d30 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
37d40 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
37d50 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
37d60 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
37d70 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
37d80 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
37d90 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
37da0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37db0 75 6c 74 5f 74 65 78 74 36 34 28 29 20 69 6e 74  ult_text64() int
37dc0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
37dd0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
37de0 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  an.** applicatio
37df0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
37e00 6f 6e 20 74 6f 20 62 65 20 61 20 74 65 78 74 20  on to be a text 
37e10 73 74 72 69 6e 67 20 69 6e 20 61 6e 20 65 6e 63  string in an enc
37e20 6f 64 69 6e 67 0a 2a 2a 20 73 70 65 63 69 66 69  oding.** specifi
37e30 65 64 20 62 79 20 74 68 65 20 66 69 66 74 68 20  ed by the fifth 
37e40 28 61 6e 64 20 6c 61 73 74 29 20 70 61 72 61 6d  (and last) param
37e50 65 74 65 72 2c 20 77 68 69 63 68 20 6d 75 73 74  eter, which must
37e60 20 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53   be one.** of [S
37e70 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
37e80 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51  LITE_UTF16], [SQ
37e90 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f  LITE_UTF16BE], o
37ea0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
37eb0 45 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74  E]..** ^SQLite t
37ec0 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
37ed0 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
37ee0 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
37ef0 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
37f00 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
37f10 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
37f20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e  interfaces..** ^
37f30 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
37f40 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
37f50 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
37f60 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
37f70 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
37f80 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
37f90 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
37fa0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
37fb0 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
37fc0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
37fd0 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
37fe0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
37ff0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
38000 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
38010 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
38020 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
38030 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
38040 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
38050 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
38060 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
38070 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
38080 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
38090 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
380a0 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
380b0 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72  sult.  If the 3r
380c0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
380d0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
380e0 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20  n it.** must be 
380f0 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20  the byte offset 
38100 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20  into the string 
38110 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
38120 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a  rminator would.*
38130 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20  * appear if the 
38140 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c  string where NUL
38150 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
38160 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
38170 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ers occur.** in 
38180 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20  the string at a 
38190 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74  byte offset that
381a0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68   is less than th
381b0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33  e value of the 3
381c0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  rd.** parameter,
381d0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
381e0 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  ing string will 
381f0 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
38200 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a   NULs and the.**
38210 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
38220 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67  ssions operating
38230 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68   on strings with
38240 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
38250 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
38260 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
38270 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
38280 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
38290 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
382a0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
382b0 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d  t_blob is a non-
382c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
382d0 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20  en SQLite calls 
382e0 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  that.** function
382f0 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74   as the destruct
38300 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f  or on the text o
38310 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68  r BLOB result wh
38320 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
38330 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
38340 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
38350 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
38360 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
38370 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
38380 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a  terfaces or to.*
38390 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
383a0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
383b0 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
383c0 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65  LITE_STATIC, the
383d0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75  n SQLite.** assu
383e0 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78  mes that the tex
383f0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
38400 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20   is in constant 
38410 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
38420 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63  ot.** copy the c
38430 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61  ontent of the pa
38440 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c  rameter nor call
38450 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e   a destructor on
38460 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   the content.** 
38470 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
38480 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
38490 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
384a0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
384b0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
384c0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
384d0 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
384e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
384f0 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
38500 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
38510 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
38520 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
38530 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
38540 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
38550 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
38560 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
38570 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
38580 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
38590 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
385a0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
385b0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
385c0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
385d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
385e0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
385f0 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
38600 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
38610 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
38620 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
38630 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
38640 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  eter.  ^The.** s
38650 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
38660 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
38670 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
38680 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
38690 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74  ue].** so that t
386a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
386b0 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  e] specified in 
386c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  the parameter ma
386d0 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62  y change or.** b
386e0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66  e deallocated af
386f0 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ter sqlite3_resu
38700 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72  lt_value() retur
38710 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  ns without harm.
38720 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65  .** ^A [protecte
38730 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
38740 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
38750 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
38760 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
38770 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
38780 65 5d 20 6f 62 6a 65 63 74 20 69 73 20