System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact d466b54789dff4fb0238b9232e74896deaefab94:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  ** This file is 
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20  an amalgamation 
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65  of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20   C source files 
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76  from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 37 2e 31 36 2e 32 2e  ersion 3.7.16.2.
00b0: 20 20 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61    By combining a
00c0: 6c 6c 20 74 68 65 20 69 6e 64 69 76 69 64 75 61  ll the individua
00d0: 6c 20 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69  l C code files i
00e0: 6e 74 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e  nto this .** sin
00f0: 67 6c 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20  gle large file, 
0100: 74 68 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20  the entire code 
0110: 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  can be compiled 
0120: 61 73 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e  as a single tran
0130: 73 6c 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e  slation.** unit.
0140: 20 20 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61    This allows ma
0150: 6e 79 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20  ny compilers to 
0160: 64 6f 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  do optimizations
0170: 20 74 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20   that would not 
0180: 62 65 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69  be.** possible i
0190: 66 20 74 68 65 20 66 69 6c 65 73 20 77 65 72 65  f the files were
01a0: 20 63 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61   compiled separa
01b0: 74 65 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e  tely.  Performan
01c0: 63 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a  ce improvements.
01d0: 2a 2a 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65  ** of 5% or more
01e0: 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65   are commonly se
01f0: 65 6e 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  en when SQLite i
0200: 73 20 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20  s compiled as a 
0210: 73 69 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c  single.** transl
0220: 61 74 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a  ation unit..**.*
0230: 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 61  * This file is a
0240: 6c 6c 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63  ll you need to c
0250: 6f 6d 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20  ompile SQLite.  
0260: 54 6f 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e  To use SQLite in
0270: 20 6f 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61   other.** progra
0280: 6d 73 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69  ms, you need thi
0290: 73 20 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22  s file and the "
02a0: 73 71 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65  sqlite3.h" heade
02b0: 72 20 66 69 6c 65 20 74 68 61 74 20 64 65 66 69  r file that defi
02c0: 6e 65 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72  nes.** the progr
02d0: 61 6d 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65  amming interface
02e0: 20 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   to the SQLite l
02f0: 69 62 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75  ibrary.  (If you
0300: 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a   do not have .**
0310: 20 74 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22   the "sqlite3.h"
0320: 20 68 65 61 64 65 72 20 66 69 6c 65 20 61 74 20   header file at 
0330: 68 61 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66  hand, you will f
0340: 69 6e 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64  ind a copy embed
0350: 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  ded within.** th
0360: 65 20 74 65 78 74 20 6f 66 20 74 68 69 73 20 66  e text of this f
0370: 69 6c 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72  ile.  Search for
0380: 20 22 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c   "Begin file sql
0390: 69 74 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20  ite3.h" to find 
03a0: 74 68 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20  the start.** of 
03b0: 74 68 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c  the embedded sql
03c0: 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 69  ite3.h header fi
03d0: 6c 65 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20  le.) Additional 
03e0: 63 6f 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62  code files may b
03f0: 65 20 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79  e needed.** if y
0400: 6f 75 20 77 61 6e 74 20 61 20 77 72 61 70 70 65  ou want a wrappe
0410: 72 20 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53  r to interface S
0420: 51 4c 69 74 65 20 77 69 74 68 20 79 6f 75 72 20  QLite with your 
0430: 63 68 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61  choice of progra
0440: 6d 6d 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67  mming.** languag
0450: 65 2e 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20  e. The code for 
0460: 74 68 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f  the "sqlite3" co
0470: 6d 6d 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c  mmand-line shell
0480: 20 69 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a   is also in a.**
0490: 20 73 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20   separate file. 
04a0: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69  This file contai
04b0: 6e 73 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72  ns only code for
04c0: 20 74 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65   the core SQLite
04d0: 20 6c 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65   library..*/.#de
04e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45  fine SQLITE_CORE
04f0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
0500: 45 5f 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31  E_AMALGAMATION 1
0510: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
0520: 50 52 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65  PRIVATE.# define
0530: 20 53 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20   SQLITE_PRIVATE 
0540: 73 74 61 74 69 63 0a 23 65 6e 64 69 66 0a 23 69  static.#endif.#i
0550: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49  fndef SQLITE_API
0560: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
0570: 5f 41 50 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a  _API.#endif./***
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69  *********** Begi
0590: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74  n file sqliteInt
05a0: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .h *************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a  **********/./*.*
05d0: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72  * 2001 September
05e0: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75   15.**.** The au
05f0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
0600: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
0610: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
0620: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0630: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0640: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
0650: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
0660: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
0670: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0680: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0690: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
06a0: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
06b0: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
06c0: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
06d0: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
06e0: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
06f0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0740: 2a 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69  **.** Internal i
0750: 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74  nterface definit
0760: 69 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e  ions for SQLite.
0770: 0a 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f  .**.*/.#ifndef _
0780: 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65  SQLITEINT_H_.#de
0790: 66 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f  fine _SQLITEINT_
07a0: 48 5f 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20  H_../*.** These 
07b0: 23 64 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20  #defines should 
07c0: 65 6e 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65  enable >2GB file
07d0: 20 73 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49   support on POSI
07e0: 58 20 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  X if the.** unde
07f0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
0800: 20 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73   system supports
0810: 20 69 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20   it.  If the OS 
0820: 6c 61 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66  lacks.** large f
0830: 69 6c 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20  ile support, or 
0840: 69 66 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e  if the OS is win
0850: 64 6f 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75  dows, these shou
0860: 6c 64 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  ld be no-ops..**
0870: 0a 2a 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39  .** Ticket #2739
0880: 3a 20 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c  :  The _LARGEFIL
0890: 45 5f 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d  E_SOURCE macro m
08a0: 75 73 74 20 61 70 70 65 61 72 20 62 65 66 6f 72  ust appear befor
08b0: 65 20 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20  e any.** system 
08c0: 23 69 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63  #includes.  Henc
08d0: 65 2c 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66  e, this block of
08e0: 20 63 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68   code must be th
08f0: 65 20 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20  e very first.** 
0900: 63 6f 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72  code in all sour
0910: 63 65 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  ce files..**.** 
0920: 4c 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f  Large file suppo
0930: 72 74 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c  rt can be disabl
0940: 65 64 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53  ed using the -DS
0950: 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46  QLITE_DISABLE_LF
0960: 53 20 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74  S switch.** on t
0970: 68 65 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d  he compiler comm
0980: 61 6e 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20  and line.  This 
0990: 69 73 20 6e 65 63 65 73 73 61 72 79 20 69 66 20  is necessary if 
09a0: 79 6f 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e  you are compilin
09b0: 67 0a 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74  g.** on a recent
09c0: 20 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65   machine (ex: Re
09d0: 64 20 48 61 74 20 37 2e 32 29 20 62 75 74 20 79  d Hat 7.2) but y
09e0: 6f 75 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64  ou want your cod
09f0: 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20  e to work.** on 
0a00: 61 6e 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65  an older machine
0a10: 20 28 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e   (ex: Red Hat 6.
0a20: 30 29 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70  0).  If you comp
0a30: 69 6c 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37  ile on Red Hat 7
0a40: 2e 32 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68  .2.** without th
0a50: 69 73 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69  is option, LFS i
0a60: 73 20 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c  s enable.  But L
0a70: 46 53 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73  FS does not exis
0a80: 74 20 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a  t in the kernel.
0a90: 2a 2a 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e  ** in Red Hat 6.
0aa0: 30 2c 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77  0, so the code w
0ab0: 6f 6e 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63  on't work.  Henc
0ac0: 65 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62  e, for maximum b
0ad0: 69 6e 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69  inary.** portabi
0ae0: 6c 69 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20  lity you should 
0af0: 6f 6d 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20  omit LFS..**.** 
0b00: 53 69 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20  Similar is true 
0b10: 66 6f 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c  for Mac OS X.  L
0b20: 46 53 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f  FS is only suppo
0b30: 72 74 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58  rted on Mac OS X
0b40: 20 39 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f   9 and later..*/
0b50: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
0b60: 44 49 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65  DISABLE_LFS.# de
0b70: 66 69 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45  fine _LARGE_FILE
0b80: 20 20 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65         1.# ifnde
0b90: 66 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42  f _FILE_OFFSET_B
0ba0: 49 54 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f  ITS.#   define _
0bb0: 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53  FILE_OFFSET_BITS
0bc0: 20 36 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65   64.# endif.# de
0bd0: 66 69 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f  fine _LARGEFILE_
0be0: 53 4f 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a  SOURCE 1.#endif.
0bf0: 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74  ./*.** Include t
0c00: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
0c10: 20 68 65 61 64 65 72 20 6f 75 74 70 75 74 20 62   header output b
0c20: 79 20 27 63 6f 6e 66 69 67 75 72 65 27 20 69 66  y 'configure' if
0c30: 20 77 65 27 72 65 20 75 73 69 6e 67 20 74 68 65   we're using the
0c40: 0a 2a 2a 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73  .** autoconf-bas
0c50: 65 64 20 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64  ed build.*/.#ifd
0c60: 65 66 20 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f  ef _HAVE_SQLITE_
0c70: 43 4f 4e 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64  CONFIG_H.#includ
0c80: 65 20 22 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e  e "config.h".#en
0c90: 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  dif../**********
0ca0: 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c  **** Include sql
0cb0: 69 74 65 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68  iteLimit.h in th
0cc0: 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69  e middle of sqli
0cd0: 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a  teInt.h ********
0ce0: 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ***/./**********
0cf0: 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20  **** Begin file 
0d00: 73 71 6c 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a  sqliteLimit.h **
0d10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d30: 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20  ***/./*.** 2007 
0d40: 4d 61 79 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20  May 7.**.** The 
0d50: 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73  author disclaims
0d60: 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68   copyright to th
0d70: 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20  is source code. 
0d80: 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   In place of.** 
0d90: 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20  a legal notice, 
0da0: 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69  here is a blessi
0db0: 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79  ng:.**.**    May
0dc0: 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64   you do good and
0dd0: 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20   not evil..**   
0de0: 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f   May you find fo
0df0: 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f  rgiveness for yo
0e00: 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69  urself and forgi
0e10: 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20  ve others..**   
0e20: 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66   May you share f
0e30: 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b  reely, never tak
0e40: 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f  ing more than yo
0e50: 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a  u give..**.*****
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ea0: 2a 2a 2a 2a 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73  ****.** .** This
0eb0: 20 66 69 6c 65 20 64 65 66 69 6e 65 73 20 76 61   file defines va
0ec0: 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 6f 66 20  rious limits of 
0ed0: 77 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  what SQLite can 
0ee0: 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a  process..*/../*.
0ef0: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  ** The maximum l
0f00: 65 6e 67 74 68 20 6f 66 20 61 20 54 45 58 54 20  ength of a TEXT 
0f10: 6f 72 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73  or BLOB in bytes
0f20: 2e 20 20 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a  .   This also.**
0f30: 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65   limits the size
0f40: 20 6f 66 20 61 20 72 6f 77 20 69 6e 20 61 20 74   of a row in a t
0f50: 61 62 6c 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a  able or index..*
0f60: 2a 0a 2a 2a 20 54 68 65 20 68 61 72 64 20 6c 69  *.** The hard li
0f70: 6d 69 74 20 69 73 20 74 68 65 20 61 62 69 6c 69  mit is the abili
0f80: 74 79 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73  ty of a 32-bit s
0f90: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
0fa0: 20 74 6f 20 63 6f 75 6e 74 20 74 68 65 20 73 69   to count the si
0fb0: 7a 65 3a 20 32 5e 33 31 2d 31 20 6f 72 20 32 31  ze: 2^31-1 or 21
0fc0: 34 37 34 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66  47483647..*/.#if
0fd0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ndef SQLITE_MAX_
0fe0: 4c 45 4e 47 54 48 0a 23 20 64 65 66 69 6e 65 20  LENGTH.# define 
0ff0: 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54  SQLITE_MAX_LENGT
1000: 48 20 31 30 30 30 30 30 30 30 30 30 0a 23 65 6e  H 1000000000.#en
1010: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20  dif../*.** This 
1020: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  is the maximum n
1030: 75 6d 62 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20  umber of.**.**  
1040: 20 20 2a 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61    * Columns in a
1050: 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43   table.**    * C
1060: 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
1070: 65 78 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d  ex.**    * Colum
1080: 6e 73 20 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20  ns in a view.** 
1090: 20 20 20 2a 20 54 65 72 6d 73 20 69 6e 20 74 68     * Terms in th
10a0: 65 20 53 45 54 20 63 6c 61 75 73 65 20 6f 66 20  e SET clause of 
10b0: 61 6e 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  an UPDATE statem
10c0: 65 6e 74 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d  ent.**    * Term
10d0: 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
10e0: 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20  set of a SELECT 
10f0: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20  statement.**    
1100: 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20 47  * Terms in the G
1110: 52 4f 55 50 20 42 59 20 6f 72 20 4f 52 44 45 52  ROUP BY or ORDER
1120: 20 42 59 20 63 6c 61 75 73 65 73 20 6f 66 20 61   BY clauses of a
1130: 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1140: 74 2e 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73  t..**    * Terms
1150: 20 69 6e 20 74 68 65 20 56 41 4c 55 45 53 20 63   in the VALUES c
1160: 6c 61 75 73 65 20 6f 66 20 61 6e 20 49 4e 53 45  lause of an INSE
1170: 52 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  RT statement.**.
1180: 2a 2a 20 54 68 65 20 68 61 72 64 20 75 70 70 65  ** The hard uppe
1190: 72 20 6c 69 6d 69 74 20 68 65 72 65 20 69 73 20  r limit here is 
11a0: 33 32 36 37 36 2e 20 20 4d 6f 73 74 20 64 61 74  32676.  Most dat
11b0: 61 62 61 73 65 20 70 65 6f 70 6c 65 20 77 69 6c  abase people wil
11c0: 6c 0a 2a 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68  l.** tell you th
11d0: 61 74 20 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72  at in a well-nor
11e0: 6d 61 6c 69 7a 65 64 20 64 61 74 61 62 61 73 65  malized database
11f0: 2c 20 79 6f 75 20 75 73 75 61 6c 6c 79 20 73 68  , you usually sh
1200: 6f 75 6c 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65  ould.** not have
1210: 20 6d 6f 72 65 20 74 68 61 6e 20 61 20 64 6f 7a   more than a doz
1220: 65 6e 20 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73  en or so columns
1230: 20 69 6e 20 61 6e 79 20 74 61 62 6c 65 2e 20 20   in any table.  
1240: 41 6e 64 20 69 66 0a 2a 2a 20 74 68 61 74 20 69  And if.** that i
1250: 73 20 74 68 65 20 63 61 73 65 2c 20 74 68 65 72  s the case, ther
1260: 65 20 69 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e  e is no point in
1270: 20 68 61 76 69 6e 67 20 6d 6f 72 65 20 74 68 61   having more tha
1280: 6e 20 61 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e  n a few.** dozen
1290: 20 76 61 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f   values in any o
12a0: 66 20 74 68 65 20 6f 74 68 65 72 20 73 69 74 75  f the other situ
12b0: 61 74 69 6f 6e 73 20 64 65 73 63 72 69 62 65 64  ations described
12c0: 20 61 62 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64   above..*/.#ifnd
12d0: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f  ef SQLITE_MAX_CO
12e0: 4c 55 4d 4e 0a 23 20 64 65 66 69 6e 65 20 53 51  LUMN.# define SQ
12f0: 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20  LITE_MAX_COLUMN 
1300: 32 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  2000.#endif../*.
1310: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  ** The maximum l
1320: 65 6e 67 74 68 20 6f 66 20 61 20 73 69 6e 67 6c  ength of a singl
1330: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1340: 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20  in bytes..**.** 
1350: 49 74 20 75 73 65 64 20 74 6f 20 62 65 20 74 68  It used to be th
1360: 65 20 63 61 73 65 20 74 68 61 74 20 73 65 74 74  e case that sett
1370: 69 6e 67 20 74 68 69 73 20 76 61 6c 75 65 20 74  ing this value t
1380: 6f 20 7a 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20  o zero would.** 
1390: 74 75 72 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f  turn the limit o
13a0: 66 66 2e 20 20 54 68 61 74 20 69 73 20 6e 6f 20  ff.  That is no 
13b0: 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 49 74  longer true.  It
13c0: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
13d0: 0a 2a 2a 20 74 6f 20 74 75 72 6e 20 74 68 69 73  .** to turn this
13e0: 20 6c 69 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23   limit off..*/.#
13f0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41  ifndef SQLITE_MA
1400: 58 5f 53 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64  X_SQL_LENGTH.# d
1410: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58  efine SQLITE_MAX
1420: 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30  _SQL_LENGTH 1000
1430: 30 30 30 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f  000000.#endif../
1440: 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d  *.** The maximum
1450: 20 64 65 70 74 68 20 6f 66 20 61 6e 20 65 78 70   depth of an exp
1460: 72 65 73 73 69 6f 6e 20 74 72 65 65 2e 20 54 68  ression tree. Th
1470: 69 73 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  is is limited to
1480: 20 0a 2a 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74   .** some extent
1490: 20 62 79 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53   by SQLITE_MAX_S
14a0: 51 4c 5f 4c 45 4e 47 54 48 2e 20 42 75 74 20 73  QL_LENGTH. But s
14b0: 6f 6d 65 74 69 6d 65 20 79 6f 75 20 6d 69 67 68  ometime you migh
14c0: 74 20 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c  t .** want to pl
14d0: 61 63 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20  ace more severe 
14e0: 6c 69 6d 69 74 73 20 6f 6e 20 74 68 65 20 63 6f  limits on the co
14f0: 6d 70 6c 65 78 69 74 79 20 6f 66 20 61 6e 20 0a  mplexity of an .
1500: 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a  ** expression..*
1510: 2a 0a 2a 2a 20 41 20 76 61 6c 75 65 20 6f 66 20  *.** A value of 
1520: 30 20 75 73 65 64 20 74 6f 20 6d 65 61 6e 20 74  0 used to mean t
1530: 68 61 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61  hat the limit wa
1540: 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a  s not enforced..
1550: 2a 2a 20 42 75 74 20 74 68 61 74 20 69 73 20 6e  ** But that is n
1560: 6f 20 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20  o longer true.  
1570: 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77  The limit is now
1580: 20 73 74 72 69 63 74 6c 79 20 65 6e 66 6f 72 63   strictly enforc
1590: 65 64 0a 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d  ed.** at all tim
15a0: 65 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  es..*/.#ifndef S
15b0: 51 4c 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44  QLITE_MAX_EXPR_D
15c0: 45 50 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51  EPTH.# define SQ
15d0: 4c 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45  LITE_MAX_EXPR_DE
15e0: 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a  PTH 1000.#endif.
15f0: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d  ./*.** The maxim
1600: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
1610: 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
1620: 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1630: 74 2e 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 67  t..** The code g
1640: 65 6e 65 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d  enerator for com
1650: 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
1660: 74 65 6d 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65  tements does one
1670: 0a 2a 2a 20 6c 65 76 65 6c 20 6f 66 20 72 65 63  .** level of rec
1680: 75 72 73 69 6f 6e 20 66 6f 72 20 65 61 63 68 20  ursion for each 
1690: 74 65 72 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f  term.  A stack o
16a0: 76 65 72 66 6c 6f 77 20 63 61 6e 20 72 65 73 75  verflow can resu
16b0: 6c 74 0a 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d  lt.** if the num
16c0: 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 73 20  ber of terms is 
16d0: 74 6f 6f 20 6c 61 72 67 65 2e 20 20 49 6e 20 70  too large.  In p
16e0: 72 61 63 74 69 63 65 2c 20 6d 6f 73 74 20 53 51  ractice, most SQ
16f0: 4c 0a 2a 2a 20 6e 65 76 65 72 20 68 61 73 20 6d  L.** never has m
1700: 6f 72 65 20 74 68 61 6e 20 33 20 6f 72 20 34 20  ore than 3 or 4 
1710: 74 65 72 6d 73 2e 20 20 55 73 65 20 61 20 76 61  terms.  Use a va
1720: 6c 75 65 20 6f 66 20 30 20 74 6f 20 64 69 73 61  lue of 0 to disa
1730: 62 6c 65 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74  ble.** any limit
1740: 20 6f 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   on the number o
1750: 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
1760: 70 6f 75 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f  pount SELECT..*/
1770: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
1780: 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MAX_COMPOUND_SEL
1790: 45 43 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ECT.# define SQL
17a0: 49 54 45 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44  ITE_MAX_COMPOUND
17b0: 5f 53 45 4c 45 43 54 20 35 30 30 0a 23 65 6e 64  _SELECT 500.#end
17c0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61  if../*.** The ma
17d0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
17e0: 6f 70 63 6f 64 65 73 20 69 6e 20 61 20 56 44 42  opcodes in a VDB
17f0: 45 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f  E program..** No
1800: 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f  t currently enfo
1810: 72 63 65 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  rced..*/.#ifndef
1820: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45   SQLITE_MAX_VDBE
1830: 5f 4f 50 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  _OP.# define SQL
1840: 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20  ITE_MAX_VDBE_OP 
1850: 32 35 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a  25000.#endif../*
1860: 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20  .** The maximum 
1870: 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
1880: 6e 74 73 20 74 6f 20 61 6e 20 53 51 4c 20 66 75  nts to an SQL fu
1890: 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64  nction..*/.#ifnd
18a0: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55  ef SQLITE_MAX_FU
18b0: 4e 43 54 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66  NCTION_ARG.# def
18c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46  ine SQLITE_MAX_F
18d0: 55 4e 43 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a  UNCTION_ARG 127.
18e0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
18f0: 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1900: 20 6f 66 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61   of in-memory pa
1910: 67 65 73 20 74 6f 20 75 73 65 20 66 6f 72 20 74  ges to use for t
1920: 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
1930: 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 66 6f  .** table and fo
1940: 72 20 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c  r temporary tabl
1950: 65 73 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  es.  The SQLITE_
1960: 44 45 46 41 55 4c 54 5f 43 41 43 48 45 5f 53 49  DEFAULT_CACHE_SI
1970: 5a 45 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  ZE.*/.#ifndef SQ
1980: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43  LITE_DEFAULT_CAC
1990: 48 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65  HE_SIZE.# define
19a0: 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f   SQLITE_DEFAULT_
19b0: 43 41 43 48 45 5f 53 49 5a 45 20 20 32 30 30 30  CACHE_SIZE  2000
19c0: 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20  .#endif.#ifndef 
19d0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 54  SQLITE_DEFAULT_T
19e0: 45 4d 50 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23  EMP_CACHE_SIZE.#
19f0: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44   define SQLITE_D
1a00: 45 46 41 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48  EFAULT_TEMP_CACH
1a10: 45 5f 53 49 5a 45 20 20 35 30 30 0a 23 65 6e 64  E_SIZE  500.#end
1a20: 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65  if../*.** The de
1a30: 66 61 75 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20  fault number of 
1a40: 66 72 61 6d 65 73 20 74 6f 20 61 63 63 75 6d 75  frames to accumu
1a50: 6c 61 74 65 20 69 6e 20 74 68 65 20 6c 6f 67 20  late in the log 
1a60: 66 69 6c 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63  file before.** c
1a70: 68 65 63 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65  heckpointing the
1a80: 20 64 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c   database in WAL
1a90: 20 6d 6f 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65   mode..*/.#ifnde
1aa0: 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54  f SQLITE_DEFAULT
1ab0: 5f 57 41 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f  _WAL_AUTOCHECKPO
1ac0: 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  INT.# define SQL
1ad0: 49 54 45 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f  ITE_DEFAULT_WAL_
1ae0: 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20  AUTOCHECKPOINT  
1af0: 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  1000.#endif../*.
1b00: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  ** The maximum n
1b10: 75 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68 65  umber of attache
1b20: 64 20 64 61 74 61 62 61 73 65 73 2e 20 20 54 68  d databases.  Th
1b30: 69 73 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  is must be betwe
1b40: 65 6e 20 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20  en 0.** and 62. 
1b50: 20 54 68 65 20 75 70 70 65 72 20 62 6f 75 6e 64   The upper bound
1b60: 20 6f 6e 20 36 32 20 69 73 20 62 65 63 61 75 73   on 62 is becaus
1b70: 65 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67  e a 64-bit integ
1b80: 65 72 20 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20  er bitmap.** is 
1b90: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
1ba0: 74 6f 20 74 72 61 63 6b 20 61 74 74 61 63 68 65  to track attache
1bb0: 64 20 64 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a  d databases..*/.
1bc0: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  #ifndef SQLITE_M
1bd0: 41 58 5f 41 54 54 41 43 48 45 44 0a 23 20 64 65  AX_ATTACHED.# de
1be0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f  fine SQLITE_MAX_
1bf0: 41 54 54 41 43 48 45 44 20 31 30 0a 23 65 6e 64  ATTACHED 10.#end
1c00: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d  if.../*.** The m
1c10: 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20  aximum value of 
1c20: 61 20 3f 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20  a ?nnn wildcard 
1c30: 74 68 61 74 20 74 68 65 20 70 61 72 73 65 72 20  that the parser 
1c40: 77 69 6c 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a  will accept..*/.
1c50: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  #ifndef SQLITE_M
1c60: 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  AX_VARIABLE_NUMB
1c70: 45 52 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  ER.# define SQLI
1c80: 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f  TE_MAX_VARIABLE_
1c90: 4e 55 4d 42 45 52 20 39 39 39 0a 23 65 6e 64 69  NUMBER 999.#endi
1ca0: 66 0a 0a 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61  f../* Maximum pa
1cb0: 67 65 20 73 69 7a 65 2e 20 20 54 68 65 20 75 70  ge size.  The up
1cc0: 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69  per bound on thi
1cd0: 73 20 76 61 6c 75 65 20 69 73 20 36 35 35 33 36  s value is 65536
1ce0: 2e 20 20 54 68 69 73 20 61 20 6c 69 6d 69 74 0a  .  This a limit.
1cf0: 2a 2a 20 69 6d 70 6f 73 65 64 20 62 79 20 74 68  ** imposed by th
1d00: 65 20 75 73 65 20 6f 66 20 31 36 2d 62 69 74 20  e use of 16-bit 
1d10: 6f 66 66 73 65 74 73 20 77 69 74 68 69 6e 20 65  offsets within e
1d20: 61 63 68 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20  ach page..**.** 
1d30: 45 61 72 6c 69 65 72 20 76 65 72 73 69 6f 6e 73  Earlier versions
1d40: 20 6f 66 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77   of SQLite allow
1d50: 65 64 20 74 68 65 20 75 73 65 72 20 74 6f 20 63  ed the user to c
1d60: 68 61 6e 67 65 20 74 68 69 73 20 76 61 6c 75 65  hange this value
1d70: 20 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74   at.** compile t
1d80: 69 6d 65 2e 20 54 68 69 73 20 69 73 20 6e 6f 20  ime. This is no 
1d90: 6c 6f 6e 67 65 72 20 70 65 72 6d 69 74 74 65 64  longer permitted
1da0: 2c 20 6f 6e 20 74 68 65 20 67 72 6f 75 6e 64 73  , on the grounds
1db0: 20 74 68 61 74 20 69 74 20 63 72 65 61 74 65 73   that it creates
1dc0: 0a 2a 2a 20 61 20 6c 69 62 72 61 72 79 20 74 68  .** a library th
1dd0: 61 74 20 69 73 20 74 65 63 68 6e 69 63 61 6c 6c  at is technicall
1de0: 79 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77  y incompatible w
1df0: 69 74 68 20 61 6e 20 53 51 4c 69 74 65 20 6c 69  ith an SQLite li
1e00: 62 72 61 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c  brary .** compil
1e10: 65 64 20 77 69 74 68 20 61 20 64 69 66 66 65 72  ed with a differ
1e20: 65 6e 74 20 6c 69 6d 69 74 2e 20 49 66 20 61 20  ent limit. If a 
1e30: 70 72 6f 63 65 73 73 20 6f 70 65 72 61 74 69 6e  process operatin
1e40: 67 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  g on a database 
1e50: 0a 2a 2a 20 77 69 74 68 20 61 20 70 61 67 65 2d  .** with a page-
1e60: 73 69 7a 65 20 6f 66 20 36 35 35 33 36 20 62 79  size of 65536 by
1e70: 74 65 73 20 63 72 61 73 68 65 73 2c 20 74 68 65  tes crashes, the
1e80: 6e 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  n an instance of
1e90: 20 53 51 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70   SQLite .** comp
1ea0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 64 65  iled with the de
1eb0: 66 61 75 6c 74 20 70 61 67 65 2d 73 69 7a 65 20  fault page-size 
1ec0: 6c 69 6d 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62  limit will not b
1ed0: 65 20 61 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61  e able to rollba
1ee0: 63 6b 20 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74  ck .** the abort
1ef0: 65 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ed transaction. 
1f00: 54 68 69 73 20 63 6f 75 6c 64 20 6c 65 61 64 20  This could lead 
1f10: 74 6f 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  to database corr
1f20: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65  uption..*/.#ifde
1f30: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47  f SQLITE_MAX_PAG
1f40: 45 5f 53 49 5a 45 0a 23 20 75 6e 64 65 66 20 53  E_SIZE.# undef S
1f50: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53  QLITE_MAX_PAGE_S
1f60: 49 5a 45 0a 23 65 6e 64 69 66 0a 23 64 65 66 69  IZE.#endif.#defi
1f70: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41  ne SQLITE_MAX_PA
1f80: 47 45 5f 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a  GE_SIZE 65536...
1f90: 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  /*.** The defaul
1fa0: 74 20 73 69 7a 65 20 6f 66 20 61 20 64 61 74 61  t size of a data
1fb0: 62 61 73 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69  base page..*/.#i
1fc0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46  fndef SQLITE_DEF
1fd0: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23  AULT_PAGE_SIZE.#
1fe0: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44   define SQLITE_D
1ff0: 45 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45  EFAULT_PAGE_SIZE
2000: 20 31 30 32 34 0a 23 65 6e 64 69 66 0a 23 69 66   1024.#endif.#if
2010: 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f   SQLITE_DEFAULT_
2020: 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45  PAGE_SIZE>SQLITE
2030: 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23  _MAX_PAGE_SIZE.#
2040: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45   undef SQLITE_DE
2050: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a  FAULT_PAGE_SIZE.
2060: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2070: 44 45 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a  DEFAULT_PAGE_SIZ
2080: 45 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47  E SQLITE_MAX_PAG
2090: 45 5f 53 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f  E_SIZE.#endif../
20a0: 2a 0a 2a 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c  *.** Ordinarily,
20b0: 20 69 66 20 6e 6f 20 76 61 6c 75 65 20 69 73 20   if no value is 
20c0: 65 78 70 6c 69 63 69 74 6c 79 20 70 72 6f 76 69  explicitly provi
20d0: 64 65 64 2c 20 53 51 4c 69 74 65 20 63 72 65 61  ded, SQLite crea
20e0: 74 65 73 20 64 61 74 61 62 61 73 65 73 0a 2a 2a  tes databases.**
20f0: 20 77 69 74 68 20 70 61 67 65 20 73 69 7a 65 20   with page size 
2100: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50  SQLITE_DEFAULT_P
2110: 41 47 45 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65  AGE_SIZE. Howeve
2120: 72 2c 20 62 61 73 65 64 20 6f 6e 20 63 65 72 74  r, based on cert
2130: 61 69 6e 0a 2a 2a 20 64 65 76 69 63 65 20 63 68  ain.** device ch
2140: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 28 73  aracteristics (s
2150: 65 63 74 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61  ector-size and a
2160: 74 6f 6d 69 63 20 77 72 69 74 65 28 29 20 73 75  tomic write() su
2170: 70 70 6f 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74  pport),.** SQLit
2180: 65 20 6d 61 79 20 63 68 6f 6f 73 65 20 61 20 6c  e may choose a l
2190: 61 72 67 65 72 20 76 61 6c 75 65 2e 20 54 68 69  arger value. Thi
21a0: 73 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 74 68  s constant is th
21b0: 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a  e maximum value.
21c0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63  ** SQLite will c
21d0: 68 6f 6f 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e  hoose on its own
21e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
21f0: 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f  ITE_MAX_DEFAULT_
2200: 50 41 47 45 5f 53 49 5a 45 0a 23 20 64 65 66 69  PAGE_SIZE.# defi
2210: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45  ne SQLITE_MAX_DE
2220: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20  FAULT_PAGE_SIZE 
2230: 38 31 39 32 0a 23 65 6e 64 69 66 0a 23 69 66 20  8192.#endif.#if 
2240: 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55  SQLITE_MAX_DEFAU
2250: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c  LT_PAGE_SIZE>SQL
2260: 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a  ITE_MAX_PAGE_SIZ
2270: 45 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  E.# undef SQLITE
2280: 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47  _MAX_DEFAULT_PAG
2290: 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20  E_SIZE.# define 
22a0: 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55  SQLITE_MAX_DEFAU
22b0: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 53 51 4c  LT_PAGE_SIZE SQL
22c0: 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a  ITE_MAX_PAGE_SIZ
22d0: 45 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a  E.#endif.../*.**
22e0: 20 4d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   Maximum number 
22f0: 6f 66 20 70 61 67 65 73 20 69 6e 20 6f 6e 65 20  of pages in one 
2300: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
2310: 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 72 65 61  *.** This is rea
2320: 6c 6c 79 20 6a 75 73 74 20 74 68 65 20 64 65 66  lly just the def
2330: 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
2340: 68 65 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  he max_page_coun
2350: 74 20 70 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69  t pragma..** Thi
2360: 73 20 76 61 6c 75 65 20 63 61 6e 20 62 65 20 6c  s value can be l
2370: 6f 77 65 72 65 64 20 28 6f 72 20 72 61 69 73 65  owered (or raise
2380: 64 29 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  d) at run-time u
2390: 73 69 6e 67 20 74 68 61 74 20 74 68 65 0a 2a 2a  sing that the.**
23a0: 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20   max_page_count 
23b0: 6d 61 63 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  macro..*/.#ifnde
23c0: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47  f SQLITE_MAX_PAG
23d0: 45 5f 43 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65  E_COUNT.# define
23e0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45   SQLITE_MAX_PAGE
23f0: 5f 43 4f 55 4e 54 20 31 30 37 33 37 34 31 38 32  _COUNT 107374182
2400: 33 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  3.#endif../*.** 
2410: 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28  Maximum length (
2420: 69 6e 20 62 79 74 65 73 29 20 6f 66 20 74 68 65  in bytes) of the
2430: 20 70 61 74 74 65 72 6e 20 69 6e 20 61 20 4c 49   pattern in a LI
2440: 4b 45 20 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70  KE or GLOB.** op
2450: 65 72 61 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64  erator..*/.#ifnd
2460: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49  ef SQLITE_MAX_LI
2470: 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
2480: 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  H.# define SQLIT
2490: 45 5f 4d 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45  E_MAX_LIKE_PATTE
24a0: 52 4e 5f 4c 45 4e 47 54 48 20 35 30 30 30 30 0a  RN_LENGTH 50000.
24b0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61  #endif../*.** Ma
24c0: 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
24d0: 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
24e0: 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76  ggers..**.** A v
24f0: 61 6c 75 65 20 6f 66 20 31 20 6d 65 61 6e 73 20  alue of 1 means 
2500: 74 68 61 74 20 61 20 74 72 69 67 67 65 72 20 70  that a trigger p
2510: 72 6f 67 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20  rogram will not 
2520: 62 65 20 61 62 6c 65 20 74 6f 20 69 74 73 65 6c  be able to itsel
2530: 66 0a 2a 2a 20 66 69 72 65 20 61 6e 79 20 74 72  f.** fire any tr
2540: 69 67 67 65 72 73 2e 20 41 20 76 61 6c 75 65 20  iggers. A value 
2550: 6f 66 20 30 20 6d 65 61 6e 73 20 74 68 61 74 20  of 0 means that 
2560: 6e 6f 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  no trigger progr
2570: 61 6d 73 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d  ams at all .** m
2580: 61 79 20 62 65 20 65 78 65 63 75 74 65 64 2e 0a  ay be executed..
2590: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
25a0: 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45  E_MAX_TRIGGER_DE
25b0: 50 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  PTH.# define SQL
25c0: 49 54 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f  ITE_MAX_TRIGGER_
25d0: 44 45 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69  DEPTH 1000.#endi
25e0: 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  f../************
25f0: 2a 2a 20 45 6e 64 20 6f 66 20 73 71 6c 69 74 65  ** End of sqlite
2600: 4c 69 6d 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a  Limit.h ********
2610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2630: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
2640: 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68  ** Continuing wh
2650: 65 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20  ere we left off 
2660: 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a  in sqliteInt.h *
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2680: 2a 2f 0a 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e  */../* Disable n
2690: 75 69 73 61 6e 63 65 20 77 61 72 6e 69 6e 67 73  uisance warnings
26a0: 20 6f 6e 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70   on Borland comp
26b0: 69 6c 65 72 73 20 2a 2f 0a 23 69 66 20 64 65 66  ilers */.#if def
26c0: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
26d0: 5f 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20  _).#pragma warn 
26e0: 2d 72 63 68 20 2f 2a 20 75 6e 72 65 61 63 68 61  -rch /* unreacha
26f0: 62 6c 65 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61  ble code */.#pra
2700: 67 6d 61 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a  gma warn -ccc /*
2710: 20 43 6f 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c   Condition is al
2720: 77 61 79 73 20 74 72 75 65 20 6f 72 20 66 61 6c  ways true or fal
2730: 73 65 20 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61  se */.#pragma wa
2740: 72 6e 20 2d 61 75 73 20 2f 2a 20 41 73 73 69 67  rn -aus /* Assig
2750: 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6e 65 76  ned value is nev
2760: 65 72 20 75 73 65 64 20 2a 2f 0a 23 70 72 61 67  er used */.#prag
2770: 6d 61 20 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20  ma warn -csu /* 
2780: 43 6f 6d 70 61 72 69 6e 67 20 73 69 67 6e 65 64  Comparing signed
2790: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f   and unsigned */
27a0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 73  .#pragma warn -s
27b0: 70 61 20 2f 2a 20 53 75 73 70 69 63 69 6f 75 73  pa /* Suspicious
27c0: 20 70 6f 69 6e 74 65 72 20 61 72 69 74 68 6d 65   pointer arithme
27d0: 74 69 63 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f  tic */.#endif../
27e0: 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 76 61 72  * Needed for var
27f0: 69 6f 75 73 20 64 65 66 69 6e 69 74 69 6f 6e 73  ious definitions
2800: 2e 2e 2e 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f  ... */.#ifndef _
2810: 47 4e 55 5f 53 4f 55 52 43 45 0a 23 20 64 65 66  GNU_SOURCE.# def
2820: 69 6e 65 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a  ine _GNU_SOURCE.
2830: 23 65 6e 64 69 66 0a 0a 23 69 66 20 64 65 66 69  #endif..#if defi
2840: 6e 65 64 28 5f 5f 4f 70 65 6e 42 53 44 5f 5f 29  ned(__OpenBSD__)
2850: 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 42 53   && !defined(_BS
2860: 44 5f 53 4f 55 52 43 45 29 0a 23 20 64 65 66 69  D_SOURCE).# defi
2870: 6e 65 20 5f 42 53 44 5f 53 4f 55 52 43 45 0a 23  ne _BSD_SOURCE.#
2880: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63  endif../*.** Inc
2890: 6c 75 64 65 20 73 74 61 6e 64 61 72 64 20 68 65  lude standard he
28a0: 61 64 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65  ader files as ne
28b0: 63 65 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65  cessary.*/.#ifde
28c0: 66 20 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a  f HAVE_STDINT_H.
28d0: 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74  #include <stdint
28e0: 2e 68 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  .h>.#endif.#ifde
28f0: 66 20 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f  f HAVE_INTTYPES_
2900: 48 0a 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74  H.#include <intt
2910: 79 70 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a  ypes.h>.#endif..
2920: 2f 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  /*.** The follow
2930: 69 6e 67 20 6d 61 63 72 6f 73 20 61 72 65 20 75  ing macros are u
2940: 73 65 64 20 74 6f 20 63 61 73 74 20 70 6f 69 6e  sed to cast poin
2950: 74 65 72 73 20 74 6f 20 69 6e 74 65 67 65 72 73  ters to integers
2960: 20 61 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 73   and.** integers
2970: 20 74 6f 20 70 6f 69 6e 74 65 72 73 2e 20 20 54   to pointers.  T
2980: 68 65 20 77 61 79 20 79 6f 75 20 64 6f 20 74 68  he way you do th
2990: 69 73 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f  is varies from o
29a0: 6e 65 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74  ne compiler.** t
29b0: 6f 20 74 68 65 20 6e 65 78 74 2c 20 73 6f 20 77  o the next, so w
29c0: 65 20 68 61 76 65 20 64 65 76 65 6c 6f 70 65 64  e have developed
29d0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
29e0: 65 74 20 6f 66 20 23 69 66 20 73 74 61 74 65 6d  et of #if statem
29f0: 65 6e 74 73 0a 2a 2a 20 74 6f 20 67 65 6e 65 72  ents.** to gener
2a00: 61 74 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  ate appropriate 
2a10: 6d 61 63 72 6f 73 20 66 6f 72 20 61 20 77 69 64  macros for a wid
2a20: 65 20 72 61 6e 67 65 20 6f 66 20 63 6f 6d 70 69  e range of compi
2a30: 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lers..**.** The 
2a40: 63 6f 72 72 65 63 74 20 22 41 4e 53 49 22 20 77  correct "ANSI" w
2a50: 61 79 20 74 6f 20 64 6f 20 74 68 69 73 20 69 73  ay to do this is
2a60: 20 74 6f 20 75 73 65 20 74 68 65 20 69 6e 74 70   to use the intp
2a70: 74 72 5f 74 20 74 79 70 65 2e 20 0a 2a 2a 20 55  tr_t type. .** U
2a80: 6e 66 6f 72 74 75 6e 61 74 65 6c 79 2c 20 74 68  nfortunately, th
2a90: 61 74 20 74 79 70 65 64 65 66 20 69 73 20 6e 6f  at typedef is no
2aa0: 74 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 61  t available on a
2ab0: 6c 6c 20 63 6f 6d 70 69 6c 65 72 73 2c 20 6f 72  ll compilers, or
2ac0: 0a 2a 2a 20 69 66 20 69 74 20 69 73 20 61 76 61  .** if it is ava
2ad0: 69 6c 61 62 6c 65 2c 20 69 74 20 72 65 71 75 69  ilable, it requi
2ae0: 72 65 73 20 61 6e 20 23 69 6e 63 6c 75 64 65 20  res an #include 
2af0: 6f 66 20 73 70 65 63 69 66 69 63 20 68 65 61 64  of specific head
2b00: 65 72 73 0a 2a 2a 20 74 68 61 74 20 76 61 72 79  ers.** that vary
2b10: 20 66 72 6f 6d 20 6f 6e 65 20 6d 61 63 68 69 6e   from one machin
2b20: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
2b30: 2a 0a 2a 2a 20 54 69 63 6b 65 74 20 23 33 38 36  *.** Ticket #386
2b40: 30 3a 20 20 54 68 65 20 6c 6c 76 6d 2d 67 63 63  0:  The llvm-gcc
2b50: 2d 34 2e 32 20 63 6f 6d 70 69 6c 65 72 20 66 72  -4.2 compiler fr
2b60: 6f 6d 20 41 70 70 6c 65 20 63 68 6f 6b 65 73 20  om Apple chokes 
2b70: 6f 6e 0a 2a 2a 20 74 68 65 20 28 28 76 6f 69 64  on.** the ((void
2b80: 2a 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d  *)&((char*)0)[X]
2b90: 29 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 42 75  ) construct.  Bu
2ba0: 74 20 4d 53 56 43 20 63 68 6f 6b 65 73 20 6f 6e  t MSVC chokes on
2bb0: 20 28 28 76 6f 69 64 2a 29 28 58 29 29 2e 0a 2a   ((void*)(X))..*
2bc0: 2a 20 53 6f 20 77 65 20 68 61 76 65 20 74 6f 20  * So we have to 
2bd0: 64 65 66 69 6e 65 20 74 68 65 20 6d 61 63 72 6f  define the macro
2be0: 73 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 77  s in different w
2bf0: 61 79 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ays depending on
2c00: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72   the.** compiler
2c10: 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64  ..*/.#if defined
2c20: 28 5f 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f  (__PTRDIFF_TYPE_
2c30: 5f 29 20 20 2f 2a 20 54 68 69 73 20 63 61 73 65  _)  /* This case
2c40: 20 73 68 6f 75 6c 64 20 77 6f 72 6b 20 66 6f 72   should work for
2c50: 20 47 43 43 20 2a 2f 0a 23 20 64 65 66 69 6e 65   GCC */.# define
2c60: 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50   SQLITE_INT_TO_P
2c70: 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28  TR(X)  ((void*)(
2c80: 5f 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f  __PTRDIFF_TYPE__
2c90: 29 28 58 29 29 0a 23 20 64 65 66 69 6e 65 20 53  )(X)).# define S
2ca0: 51 4c 49 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54  QLITE_PTR_TO_INT
2cb0: 28 58 29 20 20 28 28 69 6e 74 29 28 5f 5f 50 54  (X)  ((int)(__PT
2cc0: 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29  RDIFF_TYPE__)(X)
2cd0: 29 0a 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64  ).#elif !defined
2ce0: 28 5f 5f 47 4e 55 43 5f 5f 29 20 20 20 20 20 20  (__GNUC__)      
2cf0: 20 2f 2a 20 57 6f 72 6b 73 20 66 6f 72 20 63 6f   /* Works for co
2d00: 6d 70 69 6c 65 72 73 20 6f 74 68 65 72 20 74 68  mpilers other th
2d10: 61 6e 20 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65 66  an LLVM */.# def
2d20: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54  ine SQLITE_INT_T
2d30: 4f 5f 50 54 52 28 58 29 20 20 28 28 76 6f 69 64  O_PTR(X)  ((void
2d40: 2a 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d  *)&((char*)0)[X]
2d50: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  ).# define SQLIT
2d60: 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20  E_PTR_TO_INT(X) 
2d70: 20 28 28 69 6e 74 29 28 28 28 63 68 61 72 2a 29   ((int)(((char*)
2d80: 58 29 2d 28 63 68 61 72 2a 29 30 29 29 0a 23 65  X)-(char*)0)).#e
2d90: 6c 69 66 20 64 65 66 69 6e 65 64 28 48 41 56 45  lif defined(HAVE
2da0: 5f 53 54 44 49 4e 54 5f 48 29 20 20 20 2f 2a 20  _STDINT_H)   /* 
2db0: 55 73 65 20 74 68 69 73 20 63 61 73 65 20 69 66  Use this case if
2dc0: 20 77 65 20 68 61 76 65 20 41 4e 53 49 20 68 65   we have ANSI he
2dd0: 61 64 65 72 73 20 2a 2f 0a 23 20 64 65 66 69 6e  aders */.# defin
2de0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f  e SQLITE_INT_TO_
2df0: 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29  PTR(X)  ((void*)
2e00: 28 69 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23  (intptr_t)(X)).#
2e10: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50   define SQLITE_P
2e20: 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28  TR_TO_INT(X)  ((
2e30: 69 6e 74 29 28 69 6e 74 70 74 72 5f 74 29 28 58  int)(intptr_t)(X
2e40: 29 29 0a 23 65 6c 73 65 20 20 20 20 20 20 20 20  )).#else        
2e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e60: 20 20 2f 2a 20 47 65 6e 65 72 61 74 65 73 20 61    /* Generates a
2e70: 20 77 61 72 6e 69 6e 67 20 2d 20 62 75 74 20 69   warning - but i
2e80: 74 20 61 6c 77 61 79 73 20 77 6f 72 6b 73 20 2a  t always works *
2e90: 2f 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  /.# define SQLIT
2ea0: 45 5f 49 4e 54 5f 54 4f 5f 50 54 52 28 58 29 20  E_INT_TO_PTR(X) 
2eb0: 20 28 28 76 6f 69 64 2a 29 28 58 29 29 0a 23 20   ((void*)(X)).# 
2ec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54  define SQLITE_PT
2ed0: 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69  R_TO_INT(X)  ((i
2ee0: 6e 74 29 28 58 29 29 0a 23 65 6e 64 69 66 0a 0a  nt)(X)).#endif..
2ef0: 2f 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  /*.** The SQLITE
2f00: 5f 54 48 52 45 41 44 53 41 46 45 20 6d 61 63 72  _THREADSAFE macr
2f10: 6f 20 6d 75 73 74 20 62 65 20 64 65 66 69 6e 65  o must be define
2f20: 64 20 61 73 20 30 2c 20 31 2c 20 6f 72 20 32 2e  d as 0, 1, or 2.
2f30: 0a 2a 2a 20 30 20 6d 65 61 6e 73 20 6d 75 74 65  .** 0 means mute
2f40: 78 65 73 20 61 72 65 20 70 65 72 6d 61 6e 65 6e  xes are permanen
2f50: 74 6c 79 20 64 69 73 61 62 6c 65 20 61 6e 64 20  tly disable and 
2f60: 74 68 65 20 6c 69 62 72 61 72 79 20 69 73 20 6e  the library is n
2f70: 65 76 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 61  ever.** threadsa
2f80: 66 65 2e 20 20 31 20 6d 65 61 6e 73 20 74 68 65  fe.  1 means the
2f90: 20 6c 69 62 72 61 72 79 20 69 73 20 73 65 72 69   library is seri
2fa0: 61 6c 69 7a 65 64 20 77 68 69 63 68 20 69 73 20  alized which is 
2fb0: 74 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 6c  the highest.** l
2fc0: 65 76 65 6c 20 6f 66 20 74 68 72 65 61 64 73 61  evel of threadsa
2fd0: 66 65 74 79 2e 20 20 32 20 6d 65 61 6e 73 20 74  fety.  2 means t
2fe0: 68 65 20 6c 69 62 61 72 79 20 69 73 20 6d 75 6c  he libary is mul
2ff0: 74 69 74 68 72 65 61 64 65 64 20 2d 20 6d 75 6c  tithreaded - mul
3000: 74 69 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64 73  tiple.** threads
3010: 20 63 61 6e 20 75 73 65 20 53 51 4c 69 74 65 20   can use SQLite 
3020: 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
3030: 6f 20 74 68 72 65 61 64 73 20 74 72 79 20 74 6f  o threads try to
3040: 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
3050: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
3060: 74 69 6f 6e 20 61 74 20 74 68 65 20 73 61 6d 65  tion at the same
3070: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64   time..**.** Old
3080: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
3090: 51 4c 69 74 65 20 75 73 65 64 20 61 6e 20 6f 70  QLite used an op
30a0: 74 69 6f 6e 61 6c 20 54 48 52 45 41 44 53 41 46  tional THREADSAF
30b0: 45 20 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20 73  E macro..** We s
30c0: 75 70 70 6f 72 74 20 74 68 61 74 20 66 6f 72 20  upport that for 
30d0: 6c 65 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20 21  legacy..*/.#if !
30e0: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54  defined(SQLITE_T
30f0: 48 52 45 41 44 53 41 46 45 29 0a 23 69 66 20 64  HREADSAFE).#if d
3100: 65 66 69 6e 65 64 28 54 48 52 45 41 44 53 41 46  efined(THREADSAF
3110: 45 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  E).# define SQLI
3120: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 54 48  TE_THREADSAFE TH
3130: 52 45 41 44 53 41 46 45 0a 23 65 6c 73 65 0a 23  READSAFE.#else.#
3140: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
3150: 48 52 45 41 44 53 41 46 45 20 31 20 2f 2a 20 49  HREADSAFE 1 /* I
3160: 4d 50 3a 20 52 2d 30 37 32 37 32 2d 32 32 33 30  MP: R-07272-2230
3170: 39 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64  9 */.#endif.#end
3180: 69 66 0a 0a 2f 2a 0a 2a 2a 20 50 6f 77 65 72 73  if../*.** Powers
3190: 61 66 65 20 6f 76 65 72 77 72 69 74 65 20 69 73  afe overwrite is
31a0: 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20   on by default. 
31b0: 20 42 75 74 20 63 61 6e 20 62 65 20 74 75 72 6e   But can be turn
31c0: 65 64 20 6f 66 66 20 75 73 69 6e 67 0a 2a 2a 20  ed off using.** 
31d0: 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 50 4f 57  the -DSQLITE_POW
31e0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
31f0: 3d 30 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  =0 command-line 
3200: 6f 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64  option..*/.#ifnd
3210: 65 66 20 53 51 4c 49 54 45 5f 50 4f 57 45 52 53  ef SQLITE_POWERS
3220: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 0a 23 20  AFE_OVERWRITE.# 
3230: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 4f  define SQLITE_PO
3240: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
3250: 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  E 1.#endif../*.*
3260: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45 46  * The SQLITE_DEF
3270: 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 20 6d  AULT_MEMSTATUS m
3280: 61 63 72 6f 20 6d 75 73 74 20 62 65 20 64 65 66  acro must be def
3290: 69 6e 65 64 20 61 73 20 65 69 74 68 65 72 20 30  ined as either 0
32a0: 20 6f 72 20 31 2e 0a 2a 2a 20 49 74 20 64 65 74   or 1..** It det
32b0: 65 72 6d 69 6e 65 73 20 77 68 65 74 68 65 72 20  ermines whether 
32c0: 6f 72 20 6e 6f 74 20 74 68 65 20 66 65 61 74 75  or not the featu
32d0: 72 65 73 20 72 65 6c 61 74 65 64 20 74 6f 20 0a  res related to .
32e0: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
32f0: 5f 4d 45 4d 53 54 41 54 55 53 20 61 72 65 20 61  _MEMSTATUS are a
3300: 76 61 69 6c 61 62 6c 65 20 62 79 20 64 65 66 61  vailable by defa
3310: 75 6c 74 20 6f 72 20 6e 6f 74 2e 20 54 68 69 73  ult or not. This
3320: 20 76 61 6c 75 65 20 63 61 6e 0a 2a 2a 20 62 65   value can.** be
3330: 20 6f 76 65 72 72 69 64 64 65 6e 20 61 74 20 72   overridden at r
3340: 75 6e 74 69 6d 65 20 75 73 69 6e 67 20 74 68 65  untime using the
3350: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
3360: 29 20 41 50 49 2e 0a 2a 2f 0a 23 69 66 20 21 64  ) API..*/.#if !d
3370: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45  efined(SQLITE_DE
3380: 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 29  FAULT_MEMSTATUS)
3390: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
33a0: 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
33b0: 55 53 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  US 1.#endif../*.
33c0: 2a 2a 20 45 78 61 63 74 6c 79 20 6f 6e 65 20 6f  ** Exactly one o
33d0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
33e0: 6d 61 63 72 6f 73 20 6d 75 73 74 20 62 65 20 64  macros must be d
33f0: 65 66 69 6e 65 64 20 69 6e 20 6f 72 64 65 72 20  efined in order 
3400: 74 6f 0a 2a 2a 20 73 70 65 63 69 66 79 20 77 68  to.** specify wh
3410: 69 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ich memory alloc
3420: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
3430: 74 6f 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 20 20  to use..**.**   
3440: 20 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f    SQLITE_SYSTEM_
3450: 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20 20  MALLOC          
3460: 2f 2f 20 55 73 65 20 6e 6f 72 6d 61 6c 20 73 79  // Use normal sy
3470: 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a  stem malloc().**
3480: 20 20 20 20 20 53 51 4c 49 54 45 5f 57 49 4e 33       SQLITE_WIN3
3490: 32 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  2_MALLOC        
34a0: 20 20 20 2f 2f 20 55 73 65 20 57 69 6e 33 32 20     // Use Win32 
34b0: 6e 61 74 69 76 65 20 68 65 61 70 20 41 50 49 0a  native heap API.
34c0: 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 5a 45  **     SQLITE_ZE
34d0: 52 4f 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  RO_MALLOC       
34e0: 20 20 20 20 20 2f 2f 20 55 73 65 20 61 20 73 74       // Use a st
34f0: 75 62 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ub allocator tha
3500: 74 20 61 6c 77 61 79 73 20 66 61 69 6c 73 0a 2a  t always fails.*
3510: 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4d 45 4d  *     SQLITE_MEM
3520: 44 45 42 55 47 20 20 20 20 20 20 20 20 20 20 20  DEBUG           
3530: 20 20 20 20 2f 2f 20 44 65 62 75 67 67 69 6e 67      // Debugging
3540: 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 79 73 74   version of syst
3550: 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 0a 2a  em malloc().**.*
3560: 2a 20 4f 6e 20 57 69 6e 64 6f 77 73 2c 20 69 66  * On Windows, if
3570: 20 74 68 65 20 53 51 4c 49 54 45 5f 57 49 4e 33   the SQLITE_WIN3
3580: 32 5f 4d 41 4c 4c 4f 43 5f 56 41 4c 49 44 41 54  2_MALLOC_VALIDAT
3590: 45 20 6d 61 63 72 6f 20 69 73 20 64 65 66 69 6e  E macro is defin
35a0: 65 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20 61 73  ed and the.** as
35b0: 73 65 72 74 28 29 20 6d 61 63 72 6f 20 69 73 20  sert() macro is 
35c0: 65 6e 61 62 6c 65 64 2c 20 65 61 63 68 20 63 61  enabled, each ca
35d0: 6c 6c 20 69 6e 74 6f 20 74 68 65 20 57 69 6e 33  ll into the Win3
35e0: 32 20 6e 61 74 69 76 65 20 68 65 61 70 20 73 75  2 native heap su
35f0: 62 73 79 73 74 65 6d 0a 2a 2a 20 77 69 6c 6c 20  bsystem.** will 
3600: 63 61 75 73 65 20 48 65 61 70 56 61 6c 69 64 61  cause HeapValida
3610: 74 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 2e  te to be called.
3620: 20 20 49 66 20 68 65 61 70 20 76 61 6c 69 64 61    If heap valida
3630: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 61 69 6c  tion should fail
3640: 2c 20 61 6e 0a 2a 2a 20 61 73 73 65 72 74 69 6f  , an.** assertio
3650: 6e 20 77 69 6c 6c 20 62 65 20 74 72 69 67 67 65  n will be trigge
3660: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 28 48 69 73 74  red..**.** (Hist
3670: 6f 72 69 63 61 6c 20 6e 6f 74 65 3a 20 20 54 68  orical note:  Th
3680: 65 72 65 20 75 73 65 64 20 74 6f 20 62 65 20 73  ere used to be s
3690: 65 76 65 72 61 6c 20 6f 74 68 65 72 20 6f 70 74  everal other opt
36a0: 69 6f 6e 73 2c 20 62 75 74 20 77 65 27 76 65 0a  ions, but we've.
36b0: 2a 2a 20 70 61 72 65 64 20 69 74 20 64 6f 77 6e  ** pared it down
36c0: 20 74 6f 20 6a 75 73 74 20 74 68 65 73 65 20 74   to just these t
36d0: 68 72 65 65 2e 29 0a 2a 2a 0a 2a 2a 20 49 66 20  hree.).**.** If 
36e0: 6e 6f 6e 65 20 6f 66 20 74 68 65 20 61 62 6f 76  none of the abov
36f0: 65 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  e are defined, t
3700: 68 65 6e 20 73 65 74 20 53 51 4c 49 54 45 5f 53  hen set SQLITE_S
3710: 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 61 73 0a  YSTEM_MALLOC as.
3720: 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 0a  ** the default..
3730: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53  */.#if defined(S
3740: 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c  QLITE_SYSTEM_MAL
3750: 4c 4f 43 29 20 5c 0a 20 20 2b 20 64 65 66 69 6e  LOC) \.  + defin
3760: 65 64 28 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  ed(SQLITE_WIN32_
3770: 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64 65  MALLOC) \.  + de
3780: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 5a 45 52  fined(SQLITE_ZER
3790: 4f 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20  O_MALLOC) \.  + 
37a0: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d  defined(SQLITE_M
37b0: 45 4d 44 45 42 55 47 29 3e 31 0a 23 20 65 72 72  EMDEBUG)>1.# err
37c0: 6f 72 20 22 54 77 6f 20 6f 72 20 6d 6f 72 65 20  or "Two or more 
37d0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
37e0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f   compile-time co
37f0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
3800: 6f 6e 73 5c 0a 20 61 72 65 20 64 65 66 69 6e 65  ons\. are define
3810: 64 20 62 75 74 20 61 74 20 6d 6f 73 74 20 6f 6e  d but at most on
3820: 65 20 69 73 20 61 6c 6c 6f 77 65 64 3a 5c 0a 20  e is allowed:\. 
3830: 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41  SQLITE_SYSTEM_MA
3840: 4c 4c 4f 43 2c 20 53 51 4c 49 54 45 5f 57 49 4e  LLOC, SQLITE_WIN
3850: 33 32 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49 54  32_MALLOC, SQLIT
3860: 45 5f 4d 45 4d 44 45 42 55 47 2c 5c 0a 20 53 51  E_MEMDEBUG,\. SQ
3870: 4c 49 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43  LITE_ZERO_MALLOC
3880: 22 0a 23 65 6e 64 69 66 0a 23 69 66 20 64 65 66  ".#endif.#if def
3890: 69 6e 65 64 28 53 51 4c 49 54 45 5f 53 59 53 54  ined(SQLITE_SYST
38a0: 45 4d 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b  EM_MALLOC) \.  +
38b0: 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f   defined(SQLITE_
38c0: 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 29 20 5c 0a  WIN32_MALLOC) \.
38d0: 20 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c 49    + defined(SQLI
38e0: 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 29 20  TE_ZERO_MALLOC) 
38f0: 5c 0a 20 20 2b 20 64 65 66 69 6e 65 64 28 53 51  \.  + defined(SQ
3900: 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 3d 3d  LITE_MEMDEBUG)==
3910: 30 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  0.# define SQLIT
3920: 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20  E_SYSTEM_MALLOC 
3930: 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  1.#endif../*.** 
3940: 49 66 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43  If SQLITE_MALLOC
3950: 5f 53 4f 46 54 5f 4c 49 4d 49 54 20 69 73 20 6e  _SOFT_LIMIT is n
3960: 6f 74 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72  ot zero, then tr
3970: 79 20 74 6f 20 6b 65 65 70 20 74 68 65 0a 2a 2a  y to keep the.**
3980: 20 73 69 7a 65 73 20 6f 66 20 6d 65 6d 6f 72 79   sizes of memory
3990: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 62 65 6c   allocations bel
39a0: 6f 77 20 74 68 69 73 20 76 61 6c 75 65 20 77 68  ow this value wh
39b0: 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2f  ere possible..*/
39c0: 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28 53 51  .#if !defined(SQ
39d0: 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54  LITE_MALLOC_SOFT
39e0: 5f 4c 49 4d 49 54 29 0a 23 20 64 65 66 69 6e 65  _LIMIT).# define
39f0: 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53   SQLITE_MALLOC_S
3a00: 4f 46 54 5f 4c 49 4d 49 54 20 31 30 32 34 0a 23  OFT_LIMIT 1024.#
3a10: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 57 65 20  endif../*.** We 
3a20: 6e 65 65 64 20 74 6f 20 64 65 66 69 6e 65 20 5f  need to define _
3a30: 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 61 73 20  XOPEN_SOURCE as 
3a40: 66 6f 6c 6c 6f 77 73 20 69 6e 20 6f 72 64 65 72  follows in order
3a50: 20 74 6f 20 65 6e 61 62 6c 65 0a 2a 2a 20 72 65   to enable.** re
3a60: 63 75 72 73 69 76 65 20 6d 75 74 65 78 65 73 20  cursive mutexes 
3a70: 6f 6e 20 6d 6f 73 74 20 55 6e 69 78 20 73 79 73  on most Unix sys
3a80: 74 65 6d 73 2e 20 20 42 75 74 20 4d 61 63 20 4f  tems.  But Mac O
3a90: 53 20 58 20 69 73 20 64 69 66 66 65 72 65 6e 74  S X is different
3aa0: 2e 0a 2a 2a 20 54 68 65 20 5f 58 4f 50 45 4e 5f  ..** The _XOPEN_
3ab0: 53 4f 55 52 43 45 20 64 65 66 69 6e 65 20 63 61  SOURCE define ca
3ac0: 75 73 65 73 20 70 72 6f 62 6c 65 6d 73 20 66 6f  uses problems fo
3ad0: 72 20 4d 61 63 20 4f 53 20 58 20 77 65 20 61 72  r Mac OS X we ar
3ae0: 65 20 74 6f 6c 64 2c 0a 2a 2a 20 73 6f 20 69 74  e told,.** so it
3af0: 20 69 73 20 6f 6d 69 74 74 65 64 20 74 68 65 72   is omitted ther
3b00: 65 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23  e.  See ticket #
3b10: 32 36 37 33 2e 0a 2a 2a 0a 2a 2a 20 4c 61 74 65  2673..**.** Late
3b20: 72 20 77 65 20 6c 65 61 72 6e 20 74 68 61 74 20  r we learn that 
3b30: 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 69 73  _XOPEN_SOURCE is
3b40: 20 70 6f 6f 72 6c 79 20 6f 72 20 69 6e 63 6f 72   poorly or incor
3b50: 72 65 63 74 6c 79 0a 2a 2a 20 69 6d 70 6c 65 6d  rectly.** implem
3b60: 65 6e 74 65 64 20 6f 6e 20 73 6f 6d 65 20 73 79  ented on some sy
3b70: 73 74 65 6d 73 2e 20 20 53 6f 20 77 65 20 61 76  stems.  So we av
3b80: 6f 69 64 20 64 65 66 69 6e 69 6e 67 20 69 74 20  oid defining it 
3b90: 61 74 20 61 6c 6c 0a 2a 2a 20 69 66 20 69 74 20  at all.** if it 
3ba0: 69 73 20 61 6c 72 65 61 64 79 20 64 65 66 69 6e  is already defin
3bb0: 65 64 20 6f 72 20 69 66 20 69 74 20 69 73 20 75  ed or if it is u
3bc0: 6e 6e 65 65 64 65 64 20 62 65 63 61 75 73 65 20  nneeded because 
3bd0: 77 65 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 64 6f  we are.** not do
3be0: 69 6e 67 20 61 20 74 68 72 65 61 64 73 61 66 65  ing a threadsafe
3bf0: 20 62 75 69 6c 64 2e 20 20 54 69 63 6b 65 74 20   build.  Ticket 
3c00: 23 32 36 38 31 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  #2681..**.** See
3c10: 20 61 6c 73 6f 20 74 69 63 6b 65 74 20 23 32 37   also ticket #27
3c20: 34 31 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69  41..*/.#if !defi
3c30: 6e 65 64 28 5f 58 4f 50 45 4e 5f 53 4f 55 52 43  ned(_XOPEN_SOURC
3c40: 45 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f  E) && !defined(_
3c50: 5f 44 41 52 57 49 4e 5f 5f 29 20 5c 0a 20 26 26  _DARWIN__) \. &&
3c60: 20 21 64 65 66 69 6e 65 64 28 5f 5f 41 50 50 4c   !defined(__APPL
3c70: 45 5f 5f 29 20 26 26 20 53 51 4c 49 54 45 5f 54  E__) && SQLITE_T
3c80: 48 52 45 41 44 53 41 46 45 0a 23 20 20 64 65 66  HREADSAFE.#  def
3c90: 69 6e 65 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43  ine _XOPEN_SOURC
3ca0: 45 20 35 30 30 20 20 2f 2a 20 4e 65 65 64 65 64  E 500  /* Needed
3cb0: 20 74 6f 20 65 6e 61 62 6c 65 20 70 74 68 72 65   to enable pthre
3cc0: 61 64 20 72 65 63 75 72 73 69 76 65 20 6d 75 74  ad recursive mut
3cd0: 65 78 65 73 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a  exes */.#endif..
3ce0: 2f 2a 0a 2a 2a 20 54 68 65 20 54 43 4c 20 68 65  /*.** The TCL he
3cf0: 61 64 65 72 73 20 61 72 65 20 6f 6e 6c 79 20 6e  aders are only n
3d00: 65 65 64 65 64 20 77 68 65 6e 20 63 6f 6d 70 69  eeded when compi
3d10: 6c 69 6e 67 20 74 68 65 20 54 43 4c 20 62 69 6e  ling the TCL bin
3d20: 64 69 6e 67 73 2e 0a 2a 2f 0a 23 69 66 20 64 65  dings..*/.#if de
3d30: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 43 4c  fined(SQLITE_TCL
3d40: 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 54 43 4c  ) || defined(TCL
3d50: 53 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 3c 74  SH).# include <t
3d60: 63 6c 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  cl.h>.#endif../*
3d70: 0a 2a 2a 20 4e 44 45 42 55 47 20 61 6e 64 20 53  .** NDEBUG and S
3d80: 51 4c 49 54 45 5f 44 45 42 55 47 20 61 72 65 20  QLITE_DEBUG are 
3d90: 6f 70 70 6f 73 69 74 65 73 2e 20 20 49 74 20 73  opposites.  It s
3da0: 68 6f 75 6c 64 20 61 6c 77 61 79 73 20 62 65 20  hould always be 
3db0: 74 72 75 65 20 74 68 61 74 0a 2a 2a 20 64 65 66  true that.** def
3dc0: 69 6e 65 64 28 4e 44 45 42 55 47 29 3d 3d 21 64  ined(NDEBUG)==!d
3dd0: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45  efined(SQLITE_DE
3de0: 42 55 47 29 2e 20 20 49 66 20 74 68 69 73 20 69  BUG).  If this i
3df0: 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
3e00: 74 72 75 65 2c 0a 2a 2a 20 6d 61 6b 65 20 69 74  true,.** make it
3e10: 20 74 72 75 65 20 62 79 20 64 65 66 69 6e 69 6e   true by definin
3e20: 67 20 6f 72 20 75 6e 64 65 66 69 6e 69 6e 67 20  g or undefining 
3e30: 4e 44 45 42 55 47 2e 0a 2a 2a 0a 2a 2a 20 53 65  NDEBUG..**.** Se
3e40: 74 74 69 6e 67 20 4e 44 45 42 55 47 20 6d 61 6b  tting NDEBUG mak
3e50: 65 73 20 74 68 65 20 63 6f 64 65 20 73 6d 61 6c  es the code smal
3e60: 6c 65 72 20 61 6e 64 20 72 75 6e 20 66 61 73 74  ler and run fast
3e70: 65 72 20 62 79 20 64 69 73 61 62 6c 69 6e 67 20  er by disabling 
3e80: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 61 73  the.** number as
3e90: 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74  sert() statement
3ea0: 73 20 69 6e 20 74 68 65 20 63 6f 64 65 2e 20 20  s in the code.  
3eb0: 53 6f 20 77 65 20 77 61 6e 74 20 74 68 65 20 64  So we want the d
3ec0: 65 66 61 75 6c 74 20 61 63 74 69 6f 6e 0a 2a 2a  efault action.**
3ed0: 20 74 6f 20 62 65 20 66 6f 72 20 4e 44 45 42 55   to be for NDEBU
3ee0: 47 20 74 6f 20 62 65 20 73 65 74 20 61 6e 64 20  G to be set and 
3ef0: 4e 44 45 42 55 47 20 74 6f 20 62 65 20 75 6e 64  NDEBUG to be und
3f00: 65 66 69 6e 65 64 20 6f 6e 6c 79 20 69 66 20 53  efined only if S
3f10: 51 4c 49 54 45 5f 44 45 42 55 47 0a 2a 2a 20 69  QLITE_DEBUG.** i
3f20: 73 20 73 65 74 2e 20 20 54 68 75 73 20 4e 44 45  s set.  Thus NDE
3f30: 42 55 47 20 62 65 63 6f 6d 65 73 20 61 6e 20 6f  BUG becomes an o
3f40: 70 74 2d 69 6e 20 72 61 74 68 65 72 20 74 68 61  pt-in rather tha
3f50: 6e 20 61 6e 20 6f 70 74 2d 6f 75 74 0a 2a 2a 20  n an opt-out.** 
3f60: 66 65 61 74 75 72 65 2e 0a 2a 2f 0a 23 69 66 20  feature..*/.#if 
3f70: 21 64 65 66 69 6e 65 64 28 4e 44 45 42 55 47 29  !defined(NDEBUG)
3f80: 20 26 26 20 21 64 65 66 69 6e 65 64 28 53 51 4c   && !defined(SQL
3f90: 49 54 45 5f 44 45 42 55 47 29 20 0a 23 20 64 65  ITE_DEBUG) .# de
3fa0: 66 69 6e 65 20 4e 44 45 42 55 47 20 31 0a 23 65  fine NDEBUG 1.#e
3fb0: 6e 64 69 66 0a 23 69 66 20 64 65 66 69 6e 65 64  ndif.#if defined
3fc0: 28 4e 44 45 42 55 47 29 20 26 26 20 64 65 66 69  (NDEBUG) && defi
3fd0: 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 42 55 47  ned(SQLITE_DEBUG
3fe0: 29 0a 23 20 75 6e 64 65 66 20 4e 44 45 42 55 47  ).# undef NDEBUG
3ff0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54  .#endif../*.** T
4000: 68 65 20 74 65 73 74 63 61 73 65 28 29 20 6d 61  he testcase() ma
4010: 63 72 6f 20 69 73 20 75 73 65 64 20 74 6f 20 61  cro is used to a
4020: 69 64 20 69 6e 20 63 6f 76 65 72 61 67 65 20 74  id in coverage t
4030: 65 73 74 69 6e 67 2e 20 20 57 68 65 6e 20 0a 2a  esting.  When .*
4040: 2a 20 64 6f 69 6e 67 20 63 6f 76 65 72 61 67 65  * doing coverage
4050: 20 74 65 73 74 69 6e 67 2c 20 74 68 65 20 63 6f   testing, the co
4060: 6e 64 69 74 69 6f 6e 20 69 6e 73 69 64 65 20 74  ndition inside t
4070: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
4080: 2a 20 74 65 73 74 63 61 73 65 28 29 20 6d 75 73  * testcase() mus
4090: 74 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 62  t be evaluated b
40a0: 6f 74 68 20 74 72 75 65 20 61 6e 64 20 66 61 6c  oth true and fal
40b0: 73 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  se in order to.*
40c0: 2a 20 67 65 74 20 66 75 6c 6c 20 62 72 61 6e 63  * get full branc
40d0: 68 20 63 6f 76 65 72 61 67 65 2e 20 20 54 68 65  h coverage.  The
40e0: 20 74 65 73 74 63 61 73 65 28 29 20 6d 61 63 72   testcase() macr
40f0: 6f 20 69 73 20 69 6e 73 65 72 74 65 64 0a 2a 2a  o is inserted.**
4100: 20 74 6f 20 68 65 6c 70 20 65 6e 73 75 72 65 20   to help ensure 
4110: 61 64 65 71 75 61 74 65 20 74 65 73 74 20 63 6f  adequate test co
4120: 76 65 72 61 67 65 20 69 6e 20 70 6c 61 63 65 73  verage in places
4130: 20 77 68 65 72 65 20 73 69 6d 70 6c 65 0a 2a 2a   where simple.**
4140: 20 63 6f 6e 64 69 74 69 6f 6e 2f 64 65 63 69 73   condition/decis
4150: 69 6f 6e 20 63 6f 76 65 72 61 67 65 20 69 73 20  ion coverage is 
4160: 69 6e 61 64 65 71 75 61 74 65 2e 20 20 46 6f 72  inadequate.  For
4170: 20 65 78 61 6d 70 6c 65 2c 20 74 65 73 74 63 61   example, testca
4180: 73 65 28 29 0a 2a 2a 20 63 61 6e 20 62 65 20 75  se().** can be u
4190: 73 65 64 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  sed to make sure
41a0: 20 62 6f 75 6e 64 61 72 79 20 76 61 6c 75 65 73   boundary values
41b0: 20 61 72 65 20 74 65 73 74 65 64 2e 20 20 46 6f   are tested.  Fo
41c0: 72 0a 2a 2a 20 62 69 74 6d 61 73 6b 20 74 65 73  r.** bitmask tes
41d0: 74 73 2c 20 74 65 73 74 63 61 73 65 28 29 20 63  ts, testcase() c
41e0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6d 61  an be used to ma
41f0: 6b 65 20 73 75 72 65 20 65 61 63 68 20 62 69 74  ke sure each bit
4200: 0a 2a 2a 20 69 73 20 73 69 67 6e 69 66 69 63 61  .** is significa
4210: 6e 74 20 61 6e 64 20 75 73 65 64 20 61 74 20 6c  nt and used at l
4220: 65 61 73 74 20 6f 6e 63 65 2e 20 20 4f 6e 20 73  east once.  On s
4230: 77 69 74 63 68 20 73 74 61 74 65 6d 65 6e 74 73  witch statements
4240: 0a 2a 2a 20 77 68 65 72 65 20 6d 75 6c 74 69 70  .** where multip
4250: 6c 65 20 63 61 73 65 73 20 67 6f 20 74 6f 20 74  le cases go to t
4260: 68 65 20 73 61 6d 65 20 62 6c 6f 63 6b 20 6f 66  he same block of
4270: 20 63 6f 64 65 2c 20 74 65 73 74 63 61 73 65 28   code, testcase(
4280: 29 0a 2a 2a 20 63 61 6e 20 69 6e 73 75 72 65 20  ).** can insure 
4290: 74 68 61 74 20 61 6c 6c 20 63 61 73 65 73 20 61  that all cases a
42a0: 72 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a  re evaluated..**
42b0: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
42c0: 45 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 54 0a  E_COVERAGE_TEST.
42d0: 53 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 20  SQLITE_PRIVATE  
42e0: 20 76 6f 69 64 20 73 71 6c 69 74 65 33 43 6f 76   void sqlite3Cov
42f0: 65 72 61 67 65 28 69 6e 74 29 3b 0a 23 20 64 65  erage(int);.# de
4300: 66 69 6e 65 20 74 65 73 74 63 61 73 65 28 58 29  fine testcase(X)
4310: 20 20 69 66 28 20 58 20 29 7b 20 73 71 6c 69 74    if( X ){ sqlit
4320: 65 33 43 6f 76 65 72 61 67 65 28 5f 5f 4c 49 4e  e3Coverage(__LIN
4330: 45 5f 5f 29 3b 20 7d 0a 23 65 6c 73 65 0a 23 20  E__); }.#else.# 
4340: 64 65 66 69 6e 65 20 74 65 73 74 63 61 73 65 28  define testcase(
4350: 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  X).#endif../*.**
4360: 20 54 68 65 20 54 45 53 54 4f 4e 4c 59 20 6d 61   The TESTONLY ma
4370: 63 72 6f 20 69 73 20 75 73 65 64 20 74 6f 20 65  cro is used to e
4380: 6e 63 6c 6f 73 65 20 76 61 72 69 61 62 6c 65 20  nclose variable 
4390: 64 65 63 6c 61 72 61 74 69 6f 6e 73 20 6f 72 0a  declarations or.
43a0: 2a 2a 20 6f 74 68 65 72 20 62 69 74 73 20 6f 66  ** other bits of
43b0: 20 63 6f 64 65 20 74 68 61 74 20 61 72 65 20 6e   code that are n
43c0: 65 65 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  eeded to support
43d0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a   the arguments.*
43e0: 2a 20 77 69 74 68 69 6e 20 74 65 73 74 63 61 73  * within testcas
43f0: 65 28 29 20 61 6e 64 20 61 73 73 65 72 74 28 29  e() and assert()
4400: 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 69 66 20   macros..*/.#if 
4410: 21 64 65 66 69 6e 65 64 28 4e 44 45 42 55 47 29  !defined(NDEBUG)
4420: 20 7c 7c 20 64 65 66 69 6e 65 64 28 53 51 4c 49   || defined(SQLI
4430: 54 45 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 54  TE_COVERAGE_TEST
4440: 29 0a 23 20 64 65 66 69 6e 65 20 54 45 53 54 4f  ).# define TESTO
4450: 4e 4c 59 28 58 29 20 20 58 0a 23 65 6c 73 65 0a  NLY(X)  X.#else.
4460: 23 20 64 65 66 69 6e 65 20 54 45 53 54 4f 4e 4c  # define TESTONL
4470: 59 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  Y(X).#endif../*.
4480: 2a 2a 20 53 6f 6d 65 74 69 6d 65 73 20 77 65 20  ** Sometimes we 
4490: 6e 65 65 64 20 61 20 73 6d 61 6c 6c 20 61 6d 6f  need a small amo
44a0: 75 6e 74 20 6f 66 20 63 6f 64 65 20 73 75 63 68  unt of code such
44b0: 20 61 73 20 61 20 76 61 72 69 61 62 6c 65 20 69   as a variable i
44c0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 0a 2a 2a  nitialization.**
44d0: 20 74 6f 20 73 65 74 75 70 20 66 6f 72 20 61 20   to setup for a 
44e0: 6c 61 74 65 72 20 61 73 73 65 72 74 28 29 20 73  later assert() s
44f0: 74 61 74 65 6d 65 6e 74 2e 20 20 57 65 20 64 6f  tatement.  We do
4500: 20 6e 6f 74 20 77 61 6e 74 20 74 68 69 73 20 63   not want this c
4510: 6f 64 65 20 74 6f 0a 2a 2a 20 61 70 70 65 61 72  ode to.** appear
4520: 20 77 68 65 6e 20 61 73 73 65 72 74 28 29 20 69   when assert() i
4530: 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65  s disabled.  The
4540: 20 66 6f 6c 6c 6f 77 69 6e 67 20 6d 61 63 72 6f   following macro
4550: 20 69 73 20 74 68 65 72 65 66 6f 72 65 0a 2a 2a   is therefore.**
4560: 20 75 73 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e   used to contain
4570: 20 74 68 61 74 20 73 65 74 75 70 20 63 6f 64 65   that setup code
4580: 2e 20 20 54 68 65 20 22 56 56 41 22 20 61 63 72  .  The "VVA" acr
4590: 6f 6e 79 6d 20 73 74 61 6e 64 73 20 66 6f 72 0a  onym stands for.
45a0: 2a 2a 20 22 56 65 72 69 66 69 63 61 74 69 6f 6e  ** "Verification
45b0: 2c 20 56 61 6c 69 64 61 74 69 6f 6e 2c 20 61 6e  , Validation, an
45c0: 64 20 41 63 63 72 65 64 69 74 61 74 69 6f 6e 22  d Accreditation"
45d0: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
45e0: 73 2c 20 74 68 65 0a 2a 2a 20 63 6f 64 65 20 77  s, the.** code w
45f0: 69 74 68 69 6e 20 56 56 41 5f 4f 4e 4c 59 28 29  ithin VVA_ONLY()
4600: 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 75 6e 20 64   will only run d
4610: 75 72 69 6e 67 20 76 65 72 69 66 69 63 61 74 69  uring verificati
4620: 6f 6e 20 70 72 6f 63 65 73 73 65 73 2e 0a 2a 2f  on processes..*/
4630: 0a 23 69 66 6e 64 65 66 20 4e 44 45 42 55 47 0a  .#ifndef NDEBUG.
4640: 23 20 64 65 66 69 6e 65 20 56 56 41 5f 4f 4e 4c  # define VVA_ONL
4650: 59 28 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 20  Y(X)  X.#else.# 
4660: 64 65 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 28  define VVA_ONLY(
4670: 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  X).#endif../*.**
4680: 20 54 68 65 20 41 4c 57 41 59 53 20 61 6e 64 20   The ALWAYS and 
4690: 4e 45 56 45 52 20 6d 61 63 72 6f 73 20 73 75 72  NEVER macros sur
46a0: 72 6f 75 6e 64 20 62 6f 6f 6c 65 61 6e 20 65 78  round boolean ex
46b0: 70 72 65 73 73 69 6f 6e 73 20 77 68 69 63 68 20  pressions which 
46c0: 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64  .** are intended
46d0: 20 74 6f 20 61 6c 77 61 79 73 20 62 65 20 74 72   to always be tr
46e0: 75 65 20 6f 72 20 66 61 6c 73 65 2c 20 72 65 73  ue or false, res
46f0: 70 65 63 74 69 76 65 6c 79 2e 20 20 53 75 63 68  pectively.  Such
4700: 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20  .** expressions 
4710: 63 6f 75 6c 64 20 62 65 20 6f 6d 69 74 74 65 64  could be omitted
4720: 20 66 72 6f 6d 20 74 68 65 20 63 6f 64 65 20 63   from the code c
4730: 6f 6d 70 6c 65 74 65 6c 79 2e 20 20 42 75 74 20  ompletely.  But 
4740: 74 68 65 79 0a 2a 2a 20 61 72 65 20 69 6e 63 6c  they.** are incl
4750: 75 64 65 64 20 69 6e 20 61 20 66 65 77 20 63 61  uded in a few ca
4760: 73 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ses in order to 
4770: 65 6e 68 61 6e 63 65 20 74 68 65 20 72 65 73 69  enhance the resi
4780: 6c 69 65 6e 63 65 0a 2a 2a 20 6f 66 20 53 51 4c  lience.** of SQL
4790: 69 74 65 20 74 6f 20 75 6e 65 78 70 65 63 74 65  ite to unexpecte
47a0: 64 20 62 65 68 61 76 69 6f 72 20 2d 20 74 6f 20  d behavior - to 
47b0: 6d 61 6b 65 20 74 68 65 20 63 6f 64 65 20 22 73  make the code "s
47c0: 65 6c 66 2d 68 65 61 6c 69 6e 67 22 0a 2a 2a 20  elf-healing".** 
47d0: 6f 72 20 22 64 75 63 74 69 6c 65 22 20 72 61 74  or "ductile" rat
47e0: 68 65 72 20 74 68 61 6e 20 62 65 69 6e 67 20 22  her than being "
47f0: 62 72 69 74 74 6c 65 22 20 61 6e 64 20 63 72 61  brittle" and cra
4800: 73 68 69 6e 67 20 61 74 20 74 68 65 20 66 69 72  shing at the fir
4810: 73 74 0a 2a 2a 20 68 69 6e 74 20 6f 66 20 75 6e  st.** hint of un
4820: 70 6c 61 6e 6e 65 64 20 62 65 68 61 76 69 6f 72  planned behavior
4830: 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ..**.** In other
4840: 20 77 6f 72 64 73 2c 20 41 4c 57 41 59 53 20 61   words, ALWAYS a
4850: 6e 64 20 4e 45 56 45 52 20 61 72 65 20 61 64 64  nd NEVER are add
4860: 65 64 20 66 6f 72 20 64 65 66 65 6e 73 69 76 65  ed for defensive
4870: 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   code..**.** Whe
4880: 6e 20 64 6f 69 6e 67 20 63 6f 76 65 72 61 67 65  n doing coverage
4890: 20 74 65 73 74 69 6e 67 20 41 4c 57 41 59 53 20   testing ALWAYS 
48a0: 61 6e 64 20 4e 45 56 45 52 20 61 72 65 20 68 61  and NEVER are ha
48b0: 72 64 2d 63 6f 64 65 64 20 74 6f 0a 2a 2a 20 62  rd-coded to.** b
48c0: 65 20 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65  e true and false
48d0: 20 73 6f 20 74 68 61 74 20 74 68 65 20 75 6e 72   so that the unr
48e0: 65 61 63 68 61 62 6c 65 20 63 6f 64 65 20 74 68  eachable code th
48f0: 65 6e 20 73 70 65 63 69 66 79 20 77 69 6c 6c 0a  en specify will.
4900: 2a 2a 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65  ** not be counte
4910: 64 20 61 73 20 75 6e 74 65 73 74 65 64 20 63 6f  d as untested co
4920: 64 65 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e  de..*/.#if defin
4930: 65 64 28 53 51 4c 49 54 45 5f 43 4f 56 45 52 41  ed(SQLITE_COVERA
4940: 47 45 5f 54 45 53 54 29 0a 23 20 64 65 66 69 6e  GE_TEST).# defin
4950: 65 20 41 4c 57 41 59 53 28 58 29 20 20 20 20 20  e ALWAYS(X)     
4960: 20 28 31 29 0a 23 20 64 65 66 69 6e 65 20 4e 45   (1).# define NE
4970: 56 45 52 28 58 29 20 20 20 20 20 20 20 28 30 29  VER(X)       (0)
4980: 0a 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28  .#elif !defined(
4990: 4e 44 45 42 55 47 29 0a 23 20 64 65 66 69 6e 65  NDEBUG).# define
49a0: 20 41 4c 57 41 59 53 28 58 29 20 20 20 20 20 20   ALWAYS(X)      
49b0: 28 28 58 29 3f 31 3a 28 61 73 73 65 72 74 28 30  ((X)?1:(assert(0
49c0: 29 2c 30 29 29 0a 23 20 64 65 66 69 6e 65 20 4e  ),0)).# define N
49d0: 45 56 45 52 28 58 29 20 20 20 20 20 20 20 28 28  EVER(X)       ((
49e0: 58 29 3f 28 61 73 73 65 72 74 28 30 29 2c 31 29  X)?(assert(0),1)
49f0: 3a 30 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  :0).#else.# defi
4a00: 6e 65 20 41 4c 57 41 59 53 28 58 29 20 20 20 20  ne ALWAYS(X)    
4a10: 20 20 28 58 29 0a 23 20 64 65 66 69 6e 65 20 4e    (X).# define N
4a20: 45 56 45 52 28 58 29 20 20 20 20 20 20 20 28 58  EVER(X)       (X
4a30: 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ).#endif../*.** 
4a40: 52 65 74 75 72 6e 20 74 72 75 65 20 28 6e 6f 6e  Return true (non
4a50: 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 20 69 6e  -zero) if the in
4a60: 70 75 74 20 69 73 20 61 20 69 6e 74 65 67 65 72  put is a integer
4a70: 20 74 68 61 74 20 69 73 20 74 6f 6f 20 6c 61 72   that is too lar
4a80: 67 65 0a 2a 2a 20 74 6f 20 66 69 74 20 69 6e 20  ge.** to fit in 
4a90: 33 32 2d 62 69 74 73 2e 20 20 54 68 69 73 20 6d  32-bits.  This m
4aa0: 61 63 72 6f 20 69 73 20 75 73 65 64 20 69 6e 73  acro is used ins
4ab0: 69 64 65 20 6f 66 20 76 61 72 69 6f 75 73 20 74  ide of various t
4ac0: 65 73 74 63 61 73 65 28 29 0a 2a 2a 20 6d 61 63  estcase().** mac
4ad0: 72 6f 73 20 74 6f 20 76 65 72 69 66 79 20 74 68  ros to verify th
4ae0: 61 74 20 77 65 20 68 61 76 65 20 74 65 73 74 65  at we have teste
4af0: 64 20 53 51 4c 69 74 65 20 66 6f 72 20 6c 61 72  d SQLite for lar
4b00: 67 65 2d 66 69 6c 65 20 73 75 70 70 6f 72 74 2e  ge-file support.
4b10: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 49 53 5f 42  .*/.#define IS_B
4b20: 49 47 5f 49 4e 54 28 58 29 20 20 28 28 28 58 29  IG_INT(X)  (((X)
4b30: 26 7e 28 69 36 34 29 30 78 66 66 66 66 66 66 66  &~(i64)0xfffffff
4b40: 66 29 21 3d 30 29 0a 0a 2f 2a 0a 2a 2a 20 54 68  f)!=0)../*.** Th
4b50: 65 20 6d 61 63 72 6f 20 75 6e 6c 69 6b 65 6c 79  e macro unlikely
4b60: 28 29 20 69 73 20 61 20 68 69 6e 74 20 74 68 61  () is a hint tha
4b70: 74 20 73 75 72 72 6f 75 6e 64 73 20 61 20 62 6f  t surrounds a bo
4b80: 6f 6c 65 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  olean.** express
4b90: 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73 75 61  ion that is usua
4ba0: 6c 6c 79 20 66 61 6c 73 65 2e 20 20 4d 61 63 72  lly false.  Macr
4bb0: 6f 20 6c 69 6b 65 6c 79 28 29 20 73 75 72 72 6f  o likely() surro
4bc0: 75 6e 64 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61  unds.** a boolea
4bd0: 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 74 68 61  n expression tha
4be0: 74 20 69 73 20 75 73 75 61 6c 6c 79 20 74 72 75  t is usually tru
4bf0: 65 2e 20 20 47 43 43 20 69 73 20 61 62 6c 65 20  e.  GCC is able 
4c00: 74 6f 0a 2a 2a 20 75 73 65 20 74 68 65 73 65 20  to.** use these 
4c10: 68 69 6e 74 73 20 74 6f 20 67 65 6e 65 72 61 74  hints to generat
4c20: 65 20 62 65 74 74 65 72 20 63 6f 64 65 2c 20 73  e better code, s
4c30: 6f 6d 65 74 69 6d 65 73 2e 0a 2a 2f 0a 23 69 66  ometimes..*/.#if
4c40: 20 64 65 66 69 6e 65 64 28 5f 5f 47 4e 55 43 5f   defined(__GNUC_
4c50: 5f 29 20 26 26 20 30 0a 23 20 64 65 66 69 6e 65  _) && 0.# define
4c60: 20 6c 69 6b 65 6c 79 28 58 29 20 20 20 20 5f 5f   likely(X)    __
4c70: 62 75 69 6c 74 69 6e 5f 65 78 70 65 63 74 28 28  builtin_expect((
4c80: 58 29 2c 31 29 0a 23 20 64 65 66 69 6e 65 20 75  X),1).# define u
4c90: 6e 6c 69 6b 65 6c 79 28 58 29 20 20 5f 5f 62 75  nlikely(X)  __bu
4ca0: 69 6c 74 69 6e 5f 65 78 70 65 63 74 28 28 58 29  iltin_expect((X)
4cb0: 2c 30 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  ,0).#else.# defi
4cc0: 6e 65 20 6c 69 6b 65 6c 79 28 58 29 20 20 20 20  ne likely(X)    
4cd0: 21 21 28 58 29 0a 23 20 64 65 66 69 6e 65 20 75  !!(X).# define u
4ce0: 6e 6c 69 6b 65 6c 79 28 58 29 20 20 21 21 28 58  nlikely(X)  !!(X
4cf0: 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a  ).#endif../*****
4d00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64  ********* Includ
4d10: 65 20 73 71 6c 69 74 65 33 2e 68 20 69 6e 20 74  e sqlite3.h in t
4d20: 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c  he middle of sql
4d30: 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a  iteInt.h *******
4d40: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a  ********/./*****
4d50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20  ********* Begin 
4d60: 66 69 6c 65 20 73 71 6c 69 74 65 33 2e 68 20 2a  file sqlite3.h *
4d70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4d80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4d90: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20  ********/./*.** 
4da0: 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31  2001 September 1
4db0: 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  5.**.** The auth
4dc0: 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70  or disclaims cop
4dd0: 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73  yright to this s
4de0: 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20  ource code.  In 
4df0: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65  place of.** a le
4e00: 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65  gal notice, here
4e10: 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a   is a blessing:.
4e20: 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  **.**    May you
4e30: 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74   do good and not
4e40: 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79   evil..**    May
4e50: 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76   you find forgiv
4e60: 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65  eness for yourse
4e70: 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f  lf and forgive o
4e80: 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79  thers..**    May
4e90: 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c   you share freel
4ea0: 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20  y, never taking 
4eb0: 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69  more than you gi
4ec0: 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ve..**.*********
4ed0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4ee0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4ef0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4f00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4f10: 0a 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20  .** This header 
4f20: 66 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65  file defines the
4f30: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
4f40: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
4f50: 72 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74  ry.** presents t
4f60: 6f 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d  o client program
4f70: 73 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74  s.  If a C-funct
4f80: 69 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20  ion, structure, 
4f90: 64 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20  datatype,.** or 
4fa0: 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74  constant definit
4fb0: 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  ion does not app
4fc0: 65 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65  ear in this file
4fd0: 2c 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20  , then it is.** 
4fe0: 6e 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20  not a published 
4ff0: 41 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69  API of SQLite, i
5000: 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  s subject to cha
5010: 6e 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e  nge without.** n
5020: 6f 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c  otice, and shoul
5030: 64 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e  d not be referen
5040: 63 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20  ced by programs 
5050: 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e  that use SQLite.
5060: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
5070: 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74  he definitions t
5080: 68 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20  hat are in this 
5090: 66 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20  file are marked 
50a0: 61 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e  as.** "experimen
50b0: 74 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e  tal".  Experimen
50c0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
50d0: 72 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a  re normally new.
50e0: 2a 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65  ** features rece
50f0: 6e 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51  ntly added to SQ
5100: 4c 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74  Lite.  We do not
5110: 20 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e   anticipate chan
5120: 67 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69  ges.** to experi
5130: 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65  mental interface
5140: 73 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68  s but reserve th
5150: 65 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20  e right to make 
5160: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a  minor changes.**
5170: 20 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66   if experience f
5180: 72 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20  rom use "in the 
5190: 77 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75  wild" suggest su
51a0: 63 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70  ch changes are p
51b0: 72 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  rudent..**.** Th
51c0: 65 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e  e official C-lan
51d0: 67 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65  guage API docume
51e0: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69  ntation for SQLi
51f0: 74 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a  te is derived.**
5200: 20 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69   from comments i
5210: 6e 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68  n this file.  Th
5220: 69 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61  is file is the a
5230: 75 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75  uthoritative sou
5240: 72 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51  rce.** on how SQ
5250: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
5260: 61 72 65 20 73 75 70 70 6f 73 65 20 74 6f 20 6f  are suppose to o
5270: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
5280: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
5290: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
52a0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
52b0: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
52c0: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
52d0: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
52e0: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
52f0: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
5300: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
5310: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
5320: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
5330: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
5340: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
5350: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
5360: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
5370: 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f  ndef _SQLITE3_H_
5380: 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45  .#define _SQLITE
5390: 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73  3_H_.#include <s
53a0: 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20  tdarg.h>     /* 
53b0: 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64  Needed for the d
53c0: 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f  efinition of va_
53d0: 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d  list */../*.** M
53e0: 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20  ake sure we can 
53f0: 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20  call this stuff 
5400: 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66  from C++..*/.#if
5410: 20 30 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a   0.extern "C" {.
5420: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41  #endif.../*.** A
5430: 64 64 20 74 68 65 20 61 62 69 6c 69 74 79 20 74  dd the ability t
5440: 6f 20 6f 76 65 72 72 69 64 65 20 27 65 78 74 65  o override 'exte
5450: 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  rn'.*/.#ifndef S
5460: 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64  QLITE_EXTERN.# d
5470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54  efine SQLITE_EXT
5480: 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69  ERN extern.#endi
5490: 66 0a 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  f..#ifndef SQLIT
54a0: 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53  E_API.# define S
54b0: 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 66  QLITE_API.#endif
54c0: 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e  .../*.** These n
54d0: 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20  o-op macros are 
54e0: 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66  used in front of
54f0: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d   interfaces to m
5500: 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74  ark those.** int
5510: 65 72 66 61 63 65 73 20 61 73 20 65 69 74 68 65  erfaces as eithe
5520: 72 20 64 65 70 72 65 63 61 74 65 64 20 6f 72 20  r deprecated or 
5530: 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e  experimental.  N
5540: 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  ew applications.
5550: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73  ** should not us
5560: 65 20 64 65 70 72 65 63 61 74 65 64 20 69 6e 74  e deprecated int
5570: 65 72 66 61 63 65 73 20 2d 20 74 68 65 79 20 61  erfaces - they a
5580: 72 65 20 73 75 70 70 6f 72 74 20 66 6f 72 20 62  re support for b
5590: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
55a0: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
55b0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
55c0: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
55d0: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
55e0: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
55f0: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
5600: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
5610: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
5620: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
5630: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
5640: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
5650: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
5660: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
5670: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
5680: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
5690: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
56a0: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
56b0: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
56c0: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
56d0: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
56e0: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
56f0: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
5700: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
5710: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
5720: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
5730: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
5740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
5750: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
5760: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
5770: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
5780: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
5790: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
57a0: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
57b0: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
57c0: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
57d0: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
57e0: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
57f0: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
5800: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
5810: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
5820: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
5830: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
5840: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
5850: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
5860: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
5870: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
5880: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
5890: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
58a0: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
58b0: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
58c0: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
58d0: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
58e0: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
58f0: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
5900: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
5910: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
5920: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
5930: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
5940: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
5950: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
5960: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
5970: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
5980: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
5990: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
59a0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
59b0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
59c0: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
59d0: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
59e0: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
59f0: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
5a00: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
5a10: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
5a20: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
5a30: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
5a40: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
5a50: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
5a60: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
5a70: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
5a80: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
5a90: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
5aa0: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
5ab0: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
5ac0: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
5ad0: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
5ae0: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
5af0: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
5b00: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
5b10: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
5b20: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
5b30: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
5b40: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
5b50: 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38  e version 3.6.18
5b60: 2c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  , SQLite source 
5b70: 63 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74  code has been st
5b80: 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c  ored in the.** <
5b90: 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77  a href="http://w
5ba0: 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72  ww.fossil-scm.or
5bb0: 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69  g/">Fossil confi
5bc0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
5bd0: 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61  ent.** system</a
5be0: 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  >.  ^The SQLITE_
5bf0: 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20  SOURCE_ID macro 
5c00: 65 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20  evaluates to.** 
5c10: 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
5c20: 64 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74  dentifies a part
5c30: 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20  icular check-in 
5c40: 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74  of SQLite.** wit
5c50: 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72  hin its configur
5c60: 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74  ation management
5c70: 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53   system.  ^The S
5c80: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a  QLITE_SOURCE_ID.
5c90: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
5ca0: 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20  ns the date and 
5cb0: 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63  time of the chec
5cc0: 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61  k-in (UTC) and a
5cd0: 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f  n SHA1.** hash o
5ce0: 66 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75  f the entire sou
5cf0: 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20  rce tree..**.** 
5d00: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
5d10: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d  e3_libversion()]
5d20: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69  ,.** [sqlite3_li
5d30: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
5d40: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75  )], [sqlite3_sou
5d50: 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  rceid()],.** [sq
5d60: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
5d70: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
5d80: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65  ce_id()]..*/.#de
5d90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
5da0: 49 4f 4e 20 20 20 20 20 20 20 20 22 33 2e 37 2e  ION        "3.7.
5db0: 31 36 2e 32 22 0a 23 64 65 66 69 6e 65 20 53 51  16.2".#define SQ
5dc0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
5dd0: 42 45 52 20 33 30 30 37 30 31 36 0a 23 64 65 66  BER 3007016.#def
5de0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
5df0: 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 33 2d  E_ID      "2013-
5e00: 30 34 2d 31 32 20 31 31 3a 35 32 3a 34 33 20 63  04-12 11:52:43 c
5e10: 62 65 61 30 32 64 39 33 38 36 35 63 65 30 65 30  bea02d93865ce0e0
5e20: 36 37 38 39 64 62 39 35 66 64 39 31 36 38 65 62  6789db95fd9168eb
5e30: 61 63 39 37 30 63 37 22 0a 0a 2f 2a 0a 2a 2a 20  ac970c7"../*.** 
5e40: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
5e50: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69  me Library Versi
5e60: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45  on Numbers.** KE
5e70: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
5e80: 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33  version, sqlite3
5e90: 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20  _sourceid.**.** 
5ea0: 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  These interfaces
5eb0: 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d   provide the sam
5ec0: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  e information as
5ed0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52   the [SQLITE_VER
5ee0: 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  SION],.** [SQLIT
5ef0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
5f00: 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53  ], and [SQLITE_S
5f10: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
5f20: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a  rocessor macros.
5f30: 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63  ** but are assoc
5f40: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c  iated with the l
5f50: 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f  ibrary instead o
5f60: 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  f the header fil
5f70: 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a  e.  ^(Cautious.*
5f80: 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  * programmers mi
5f90: 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65  ght include asse
5fa0: 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20  rt() statements 
5fb0: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61  in their applica
5fc0: 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66  tion to.** verif
5fd0: 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65  y that values re
5fe0: 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
5ff0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68  interfaces match
6000: 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a   the macros in.*
6010: 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e  * the header, an
6020: 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68  d thus insure th
6030: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
6040: 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  on is.** compile
6050: 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20  d with matching 
6060: 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64  library and head
6070: 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  er files..**.** 
6080: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
6090: 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c  >.** assert( sql
60a0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
60b0: 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45  number()==SQLITE
60c0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
60d0: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
60e0: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75  rcmp(sqlite3_sou
60f0: 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53  rceid(),SQLITE_S
6100: 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a  OURCE_ID)==0 );.
6110: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d  ** assert( strcm
6120: 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  p(sqlite3_libver
6130: 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45  sion(),SQLITE_VE
6140: 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20  RSION)==0 );.** 
6150: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
6160: 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
6170: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
6180: 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  [] string consta
6190: 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  nt contains the 
61a0: 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f  text of [SQLITE_
61b0: 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72  VERSION].** macr
61c0: 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  o.  ^The sqlite3
61d0: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75  _libversion() fu
61e0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
61f0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
6200: 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  ** to the sqlite
6210: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
6220: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68  ng constant.  Th
6230: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
6240: 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69  sion().** functi
6250: 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  on is provided f
6260: 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73  or use in DLLs s
6270: 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75  ince DLL users u
6280: 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61  sually do not ha
6290: 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63  ve.** direct acc
62a0: 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f  ess to string co
62b0: 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74  nstants within t
62c0: 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a  he DLL.  ^The.**
62d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
62e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e  ion_number() fun
62f0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e  ction returns an
6300: 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74   integer equal t
6310: 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  o.** [SQLITE_VER
6320: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e  SION_NUMBER].  ^
6330: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  The sqlite3_sour
6340: 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  ceid() function 
6350: 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f  returns .** a po
6360: 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e  inter to a strin
6370: 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65  g constant whose
6380: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61   value is the sa
6390: 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53  me as the .** [S
63a0: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d  QLITE_SOURCE_ID]
63b0: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
63c0: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  macro..**.** See
63d0: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76   also: [sqlite_v
63e0: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
63f0: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
6400: 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
6410: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c  I const char sql
6420: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d  ite3_version[] =
6430: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 3b   SQLITE_VERSION;
6440: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
6450: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
6460: 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29  libversion(void)
6470: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
6480: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
6490: 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b  _sourceid(void);
64a0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
64b0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
64c0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
64d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
64e0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
64f0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
6500: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
6510: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
6520: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
6530: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
6540: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
6550: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
6560: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
6570: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
6580: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
6590: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
65a0: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
65b0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
65c0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
65d0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
65e0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
65f0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
6600: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
6610: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
6620: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
6630: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
6640: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
6650: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
6660: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
6670: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
6680: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
6690: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
66a0: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
66b0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
66c0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
66d0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
66e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
66f0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
6700: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
6710: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
6720: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
6730: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
6740: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
6750: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
6760: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
6770: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
6780: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
6790: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
67a0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
67b0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
67c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
67d0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
67e0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
67f0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
6800: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
6810: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
6820: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
6830: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
6840: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
6850: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
6860: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
6870: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
6880: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
6890: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
68a0: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
68b0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
68c0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
68d0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
68e0: 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  AGS.SQLITE_API i
68f0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nt sqlite3_compi
6900: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f  leoption_used(co
6910: 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61  nst char *zOptNa
6920: 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  me);.SQLITE_API 
6930: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
6940: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
6950: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
6960: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
6970: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
6980: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
6990: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
69a0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
69b0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
69c0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
69d0: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
69e0: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
69f0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
6a00: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
6a10: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
6a20: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
6a30: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
6a40: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
6a50: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
6a60: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
6a70: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
6a80: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
6a90: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
6aa0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
6ab0: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
6ac0: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
6ad0: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
6ae0: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
6af0: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
6b00: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
6b10: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
6b20: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
6b30: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
6b40: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
6b50: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
6b60: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
6b70: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
6b80: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
6b90: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
6ba0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
6bb0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
6bc0: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
6bd0: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
6be0: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
6bf0: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
6c00: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
6c10: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
6c20: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
6c30: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
6c40: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
6c50: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
6c60: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
6c70: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
6c80: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
6c90: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
6ca0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
6cb0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
6cc0: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
6cd0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
6ce0: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
6cf0: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
6d00: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
6d10: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
6d20: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
6d30: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
6d40: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
6d50: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
6d60: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
6d70: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
6d80: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
6d90: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
6da0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
6db0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
6dc0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
6dd0: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
6de0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
6df0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
6e00: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
6e10: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
6e20: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
6e30: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
6e40: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
6e50: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
6e60: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
6e70: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
6e80: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
6e90: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
6ea0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
6eb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
6ec0: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
6ed0: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
6ee0: 5f 4d 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20  _MUTEX].  ^(The 
6ef0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
6f00: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74  the.** sqlite3_t
6f10: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
6f20: 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20  tion shows only 
6f30: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
6f40: 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74   setting of.** t
6f50: 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f  hread safety, no
6f60: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
6f70: 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73  hanges to that s
6f80: 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a  etting made by.*
6f90: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  * sqlite3_config
6fa0: 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  (). In other wor
6fb0: 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ds, the return v
6fc0: 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
6fd0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a  3_threadsafe().*
6fe0: 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62  * is unchanged b
6ff0: 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  y calls to sqlit
7000: 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a  e3_config().)^.*
7010: 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  *.** See the [th
7020: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
7030: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
7040: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
7050: 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  mation..*/.SQLIT
7060: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
7070: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69  3_threadsafe(voi
7080: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
7090: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
70a0: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a  nnection Handle.
70b0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61  ** KEYWORDS: {da
70c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
70d0: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  n} {database con
70e0: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  nections}.**.** 
70f0: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65  Each open SQLite
7100: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70   database is rep
7110: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f  resented by a po
7120: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
7130: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  ance of.** the o
7140: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20  paque structure 
7150: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e  named "sqlite3".
7160: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74    It is useful t
7170: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71  o think of an sq
7180: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72  lite3.** pointer
7190: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20   as an object.  
71a0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
71b0: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
71c0: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
71d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
71e0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
71f0: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63  are its construc
7200: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74  tors, and [sqlit
7210: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61  e3_close()].** a
7220: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
7230: 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20  e_v2()] are its 
7240: 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68  destructors.  Th
7250: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
7260: 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  er.** interfaces
7270: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71   (such as.** [sq
7280: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
7290: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
72a0: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
72b0: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
72c0: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
72d0: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68  ] to name but th
72e0: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65  ree) that are me
72f0: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73  thods on an.** s
7300: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a  qlite3 object..*
7310: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
7320: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
7330: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7340: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
7350: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  r Types.** KEYWO
7360: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
7370: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
7380: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
7390: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
73a0: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
73b0: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
73c0: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
73d0: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
73e0: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
73f0: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
7400: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
7410: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
7420: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
7430: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
7440: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
7450: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e  ype definitions.
7460: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69  .** The sqlite_i
7470: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
7480: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65  uint64 types are
7490: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
74a0: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
74b0: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a  atibility only..
74c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
74d0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
74e0: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20  ite_int64 types 
74f0: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
7500: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  r values.** betw
7510: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38  een -92233720368
7520: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32  54775808 and +92
7530: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
7540: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54  7 inclusive.  ^T
7550: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69  he.** sqlite3_ui
7560: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
7570: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  uint64 types can
7580: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
7590: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65  alues .** betwee
75a0: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34  n 0 and +1844674
75b0: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e  4073709551615 in
75c0: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64  clusive..*/.#ifd
75d0: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
75e0: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
75f0: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
7600: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
7610: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
7620: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
7630: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
7640: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
7650: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
7660: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
7670: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
7680: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
7690: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
76a0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
76b0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
76c0: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
76d0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
76e0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
76f0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
7700: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
7710: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
7720: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
7730: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
7740: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
7750: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
7760: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
7770: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
7780: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
7790: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
77a0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
77b0: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
77c0: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
77d0: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
77e0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
77f0: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
7800: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
7810: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
7820: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
7830: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
7840: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
7850: 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tion.**.** ^The 
7860: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
7870: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
7880: 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20  e_v2() routines 
7890: 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a  are destructors.
78a0: 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  ** for the [sqli
78b0: 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  te3] object..** 
78c0: 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
78d0: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71  3_close() and sq
78e0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
78f0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
7900: 4b 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  K if.** the [sql
7910: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
7920: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73  successfully des
7930: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61  troyed and all a
7940: 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73  ssociated.** res
7950: 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c  ources are deall
7960: 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ocated..**.** ^I
7970: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
7980: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73  onnection is ass
7990: 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66  ociated with unf
79a0: 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65  inalized prepare
79b0: 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  d.** statements 
79c0: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
79d0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a  lite3_backup obj
79e0: 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65  ects then sqlite
79f0: 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c  3_close().** wil
7a00: 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61  l leave the data
7a10: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
7a20: 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20  open and return 
7a30: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
7a40: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c  * ^If sqlite3_cl
7a50: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  ose_v2() is call
7a60: 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69  ed with unfinali
7a70: 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61  zed prepared sta
7a80: 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75  tements.** and u
7a90: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
7aa0: 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20  3_backups, then 
7ab0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
7ac0: 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a  nection becomes.
7ad0: 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22  ** an unusable "
7ae0: 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69  zombie" which wi
7af0: 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
7b00: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
7b10: 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74  when the.** last
7b20: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
7b30: 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
7b40: 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c   or the last sql
7b50: 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a  ite3_backup is.*
7b60: 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65  * finished.  The
7b70: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
7b80: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
7b90: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
7ba0: 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c  e with.** host l
7bb0: 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72  anguages that ar
7bc0: 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63  e garbage collec
7bd0: 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74  ted, and where t
7be0: 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63  he order in whic
7bf0: 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73  h.** destructors
7c00: 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61   are called is a
7c10: 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  rbitrary..**.** 
7c20: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
7c30: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  uld [sqlite3_fin
7c40: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
7c50: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20  ] all [prepared 
7c60: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20  statements],.** 
7c70: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
7c80: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c  ose | close] all
7c90: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
7ca0: 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
7cb0: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20  3_backup_finish 
7cc0: 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73  | finish] all [s
7cd0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
7ce0: 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65  bjects associate
7cf0: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73  d.** with the [s
7d00: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
7d10: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69  rior to attempti
7d20: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
7d30: 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20  object.  ^If.** 
7d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
7d50: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  () is called on 
7d60: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
7d70: 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69  ection] that sti
7d80: 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61  ll has.** outsta
7d90: 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20  nding [prepared 
7da0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c  statements], [BL
7db0: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
7dc0: 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  /or.** [sqlite3_
7dd0: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
7de0: 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20  then it returns 
7df0: 53 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68  SQLITE_OK but th
7e00: 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  e deallocation.*
7e10: 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69  * of resources i
7e20: 73 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  s deferred until
7e30: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
7e40: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
7e50: 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61  B handles],.** a
7e60: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  nd [sqlite3_back
7e70: 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20  up] objects are 
7e80: 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a  also destroyed..
7e90: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71  **.** ^If an [sq
7ea0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
7eb0: 20 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65   destroyed while
7ec0: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
7ed0: 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74  s open,.** the t
7ee0: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75  ransaction is au
7ef0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
7f00: 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
7f10: 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74  he C parameter t
7f20: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
7f30: 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  (C)] and [sqlite
7f40: 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a  3_close_v2(C)].*
7f50: 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
7f60: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
7f70: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
7f80: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
7f90: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  r obtained.** fr
7fa0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
7fb0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
7fc0: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
7fd0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
7fe0: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
7ff0: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
8000: 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
8010: 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71  e3_close() or sq
8020: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
8030: 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
8040: 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  nter.** argument
8050: 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
8060: 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  o-op..*/.SQLITE_
8070: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
8080: 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b  close(sqlite3*);
8090: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
80a0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
80b0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
80c0: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
80d0: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
80e0: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
80f0: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
8100: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
8110: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
8120: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
8130: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
8140: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
8150: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
8160: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
8170: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
8180: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
8190: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
81a0: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
81b0: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
81c0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
81d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
81e0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
81f0: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
8200: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
8210: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
8220: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
8230: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
8240: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61  alize()],.** tha
8250: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c  t allows an appl
8260: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d  ication to run m
8270: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e  ultiple statemen
8280: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74  ts of SQL.** wit
8290: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75  hout having to u
82a0: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f  se a lot of C co
82b0: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de. .**.** ^The 
82c0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
82d0: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65  nterface runs ze
82e0: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38  ro or more UTF-8
82f0: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d   encoded,.** sem
8300: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20  icolon-separate 
8310: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
8320: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32  assed into its 2
8330: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20  nd argument,.** 
8340: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
8350: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
8360: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73  connection] pass
8370: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74  ed in as its 1st
8380: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
8390: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
83a0: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
83b0: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  3rd argument to.
83c0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
83d0: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ) is not NULL, t
83e0: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  hen it is invoke
83f0: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c  d for each resul
8400: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20  t row.** coming 
8410: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75  out of the evalu
8420: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
8430: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61  nts.  ^The 4th a
8440: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
8450: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
8460: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
8470: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
8480: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
8490: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
84a0: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
84b0: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
84c0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
84d0: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
84e0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
84f0: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
8500: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
8510: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
8520: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
8530: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
8540: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
8550: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
8560: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
8570: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
8580: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
8590: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
85a0: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
85b0: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
85c0: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
85d0: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
85e0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
85f0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
8600: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
8610: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
8620: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
8630: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
8640: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
8650: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
8660: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
8670: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
8680: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
8690: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
86a0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
86b0: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
86c0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
86d0: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
86e0: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
86f0: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
8700: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
8710: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  f.** of sqlite3_
8720: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
8730: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
8740: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
8750: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
8760: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
8770: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
8780: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
8790: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
87a0: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
87b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
87c0: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
87d0: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
87e0: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
87f0: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
8800: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
8810: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
8820: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
8830: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
8840: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
8850: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
8860: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
8870: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
8880: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
8890: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
88a0: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
88b0: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
88c0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
88d0: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
88e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
88f0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
8900: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
8910: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
8920: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
8930: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
8940: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
8950: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
8960: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
8970: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
8980: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
8990: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
89a0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
89b0: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
89c0: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
89d0: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
89e0: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
89f0: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
8a00: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
8a10: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
8a20: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
8a30: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
8a40: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
8a50: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
8a60: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
8a70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
8a80: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
8a90: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
8aa0: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
8ab0: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
8ac0: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
8ad0: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
8ae0: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
8af0: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
8b00: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
8b10: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
8b20: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
8b30: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
8b40: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
8b50: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
8b60: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
8b70: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
8b80: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
8b90: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
8ba0: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
8bb0: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
8bc0: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
8bd0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
8be0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
8bf0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
8c00: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
8c10: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
8c20: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
8c30: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
8c40: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72  ation must insur
8c50: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
8c60: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
8c70: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
8c80: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
8c90: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
8ca0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
8cb0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
8cc0: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
8cd0: 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65 20 63  lose [database c
8ce0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
8cf0: 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  fied by.**      
8d00: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
8d10: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
8d20: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
8d30: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
8d40: 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  ing..** <li> The
8d50: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
8d60: 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  t not modify the
8d70: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
8d80: 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  ext passed into.
8d90: 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20  **      the 2nd 
8da0: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
8db0: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
8dc0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
8dd0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
8de0: 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ul>.*/.SQLITE_
8df0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
8e00: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
8e10: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
8e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8e30: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
8e40: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
8e50: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
8e60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8e70: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
8e80: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
8e90: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
8ea0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
8eb0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
8ec0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
8ed0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
8ee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8ef0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8f00: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
8f10: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
8f20: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
8f30: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
8f40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
8f50: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
8f60: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
8f70: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8f80: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
8f90: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
8fa0: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d  _OK {error code}
8fb0: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a   {error codes}.*
8fc0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73  * KEYWORDS: {res
8fd0: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c  ult code} {resul
8fe0: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d  t codes}.**.** M
8ff0: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74  any SQLite funct
9000: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69  ions return an i
9010: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f  nteger result co
9020: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20  de from the set 
9030: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e  shown.** here in
9040: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61   order to indica
9050: 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61  te success or fa
9060: 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  ilure..**.** New
9070: 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79   error codes may
9080: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
9090: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
90a0: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  SQLite..**.** Se
90b0: 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f  e also: [SQLITE_
90c0: 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
90d0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
90e0: 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  es],.** [sqlite3
90f0: 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
9100: 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c  t()] [SQLITE_ROL
9110: 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63  LBACK | result c
9120: 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  odes]..*/.#defin
9130: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
9140: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
9150: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
9160: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
9170: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
9180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9190: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
91a0: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
91b0: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
91c0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
91d0: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
91e0: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
91f0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
9200: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
9210: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
9220: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
9230: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
9240: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
9250: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
9260: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
9270: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
9280: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
9290: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
92a0: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
92b0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
92c0: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
92d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
92e0: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
92f0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
9300: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
9310: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
9320: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
9330: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
9340: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
9350: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
9360: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
9370: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
9380: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
9390: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
93a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
93b0: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
93c0: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
93d0: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
93e0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
93f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9400: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
9410: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
9420: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
9430: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
9440: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
9450: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
9460: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
9470: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
9480: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
9490: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
94a0: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
94b0: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
94c0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
94d0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
94e0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
94f0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
9500: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
9510: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
9520: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
9530: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
9540: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
9550: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
9560: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
9570: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
9580: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
9590: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
95a0: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
95b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
95c0: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
95d0: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65  /* Database is e
95e0: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  mpty */.#define 
95f0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
9600: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
9610: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
9620: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
9630: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
9640: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
9650: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
9660: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
9670: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9680: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
9690: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
96a0: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
96b0: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
96c0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
96d0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
96e0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
96f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9700: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
9710: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
9720: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
9730: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9740: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
9750: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
9760: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
9770: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
9780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
9790: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
97a0: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
97b0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
97c0: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
97d0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
97e0: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
97f0: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
9800: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
9810: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
9820: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
9830: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
9840: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
9850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9860: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
9870: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
9880: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
9890: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
98a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f  define SQLITE_RO
98b0: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f  W         100  /
98c0: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
98d0: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77   has another row
98e0: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e   ready */.#defin
98f0: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20  e SQLITE_DONE   
9900: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c       101  /* sql
9910: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
9920: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
9930: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d  ng */./* end-of-
9940: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a  error-codes */..
9950: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9960: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
9970: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
9980: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72  S: {extended err
9990: 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64  or code} {extend
99a0: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a  ed error codes}.
99b0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78  ** KEYWORDS: {ex
99c0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
99d0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65  de} {extended re
99e0: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
99f0: 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74  * In its default
9a00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
9a10: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69  SQLite API routi
9a20: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  nes return one o
9a30: 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20  f 26 integer.** 
9a40: 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73  [SQLITE_OK | res
9a50: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
9a60: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
9a70: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20   has shown that 
9a80: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65  many of.** these
9a90: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
9aa0: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61  e too coarse-gra
9ab0: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
9ac0: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
9ad0: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
9ae0: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
9af0: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
9b00: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
9b10: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
9b20: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
9b30: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
9b40: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
9b50: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29  3.3.8 and later)
9b60: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70   include.** supp
9b70: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ort for addition
9b80: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  al result codes 
9b90: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72  that provide mor
9ba0: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
9bb0: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
9bc0: 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65  errors. The exte
9bd0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
9be0: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72  s are enabled or
9bf0: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20   disabled.** on 
9c00: 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63  a per database c
9c10: 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20  onnection basis 
9c20: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
9c30: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
9c40: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41  esult_codes()] A
9c50: 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f  PI..**.** Some o
9c60: 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  f the available 
9c70: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
9c80: 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64  codes are listed
9c90: 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61   here..** One ma
9ca0: 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d  y expect the num
9cb0: 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20  ber of extended 
9cc0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c  result codes wil
9cd0: 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f  l be expand.** o
9ce0: 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77  ver time.  Softw
9cf0: 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78  are that uses ex
9d00: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
9d10: 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63  des should expec
9d20: 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20  t.** to see new 
9d30: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20  result codes in 
9d40: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
9d50: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
9d60: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72   The SQLITE_OK r
9d70: 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20  esult code will 
9d80: 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65  never be extende
9d90: 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61  d.  It will alwa
9da0: 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79  ys.** be exactly
9db0: 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e   zero..*/.#defin
9dc0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
9dd0: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
9de0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
9df0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
9e00: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
9e10: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20  ORT_READ        
9e20: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
9e30: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
9e40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
9e50: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  TE             (
9e60: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
9e70: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
9e80: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
9e90: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  C             (S
9ea0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
9eb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
9ec0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
9ed0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51  SYNC         (SQ
9ee0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c  LITE_IOERR | (5<
9ef0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9f00: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41  ITE_IOERR_TRUNCA
9f10: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TE          (SQL
9f20: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
9f30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
9f40: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
9f50: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
9f60: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
9f70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9f80: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
9f90: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
9fa0: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
9fb0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
9fc0: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
9fd0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
9fe0: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29  _IOERR | (9<<8))
9ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a000: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20  IOERR_DELETE    
a010: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
a020: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
a030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a040: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
a050: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
a060: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
a070: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a080: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
a090: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
a0a0: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
a0b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a0c0: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20  IOERR_ACCESS    
a0d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
a0e0: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29  IOERR | (13<<8))
a0f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a100: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52  IOERR_CHECKRESER
a110: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f  VEDLOCK (SQLITE_
a120: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29  IOERR | (14<<8))
a130: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a140: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20  IOERR_LOCK      
a150: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
a160: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29  IOERR | (15<<8))
a170: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a180: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20  IOERR_CLOSE     
a190: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
a1a0: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29  IOERR | (16<<8))
a1b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a1c0: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20  IOERR_DIR_CLOSE 
a1d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
a1e0: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29  IOERR | (17<<8))
a1f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a200: 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20  IOERR_SHMOPEN   
a210: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
a220: 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29  IOERR | (18<<8))
a230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a240: 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20  IOERR_SHMSIZE   
a250: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
a260: 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29  IOERR | (19<<8))
a270: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a280: 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20  IOERR_SHMLOCK   
a290: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
a2a0: 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29  IOERR | (20<<8))
a2b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a2c0: 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20  IOERR_SHMMAP    
a2d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
a2e0: 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29  IOERR | (21<<8))
a2f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a300: 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20  IOERR_SEEK      
a310: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
a320: 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29  IOERR | (22<<8))
a330: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a340: 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45  IOERR_DELETE_NOE
a350: 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  NT      (SQLITE_
a360: 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29  IOERR | (23<<8))
a370: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a380: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43  LOCKED_SHAREDCAC
a390: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  HE      (SQLITE_
a3a0: 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29  LOCKED |  (1<<8)
a3b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
a3c0: 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20  _BUSY_RECOVERY  
a3d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
a3e0: 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38  _BUSY   |  (1<<8
a3f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
a400: 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d  E_CANTOPEN_NOTEM
a410: 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 54  PDIR      (SQLIT
a420: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c  E_CANTOPEN | (1<
a430: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
a440: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44  ITE_CANTOPEN_ISD
a450: 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  IR          (SQL
a460: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
a470: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
a480: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46  QLITE_CANTOPEN_F
a490: 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28 53  ULLPATH       (S
a4a0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
a4b0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
a4c0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
a4d0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
a4e0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
a4f0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
a500: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
a510: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
a520: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
a530: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
a540: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
a550: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
a560: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
a570: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
a580: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
a590: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
a5a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
a5b0: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
a5c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
a5d0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
a5e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
a5f0: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
a600: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
a610: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
a620: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
a630: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
a640: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
a650: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
a660: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
a670: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
a680: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
a690: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
a6a0: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
a6b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
a6c0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
a6d0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
a6e0: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
a6f0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
a700: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
a710: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
a720: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
a730: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
a740: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
a750: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
a760: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
a770: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
a780: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
a790: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
a7a0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
a7b0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
a7c0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
a7d0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
a7e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
a7f0: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
a800: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
a810: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
a820: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
a830: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
a840: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
a850: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
a860: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
a870: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
a880: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
a890: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62  ns.**.** These b
a8a0: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  it values are in
a8b0: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
a8c0: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72  n the.** 3rd par
a8d0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
a8e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
a8f0: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a  ] interface and.
a900: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61  ** in the 4th pa
a910: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
a920: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
a930: 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64  n] method..*/.#d
a940: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
a950: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20  N_READONLY      
a960: 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f     0x00000001  /
a970: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
a980: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
a990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
a9a0: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20  N_READWRITE     
a9b0: 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f     0x00000002  /
a9c0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
a9d0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
a9e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
a9f0: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20  N_CREATE        
aa00: 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f     0x00000004  /
aa10: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
aa20: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
aa30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
aa40: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20  N_DELETEONCLOSE 
aa50: 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f     0x00000008  /
aa60: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
aa70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
aa80: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  N_EXCLUSIVE     
aa90: 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f     0x00000010  /
aaa0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
aab0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
aac0: 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20  N_AUTOPROXY     
aad0: 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f     0x00000020  /
aae0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
aaf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
ab00: 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20  N_URI           
ab10: 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f     0x00000040  /
ab20: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
ab30: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
ab40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
ab50: 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20  N_MEMORY        
ab60: 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f     0x00000080  /
ab70: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
ab80: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
ab90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
aba0: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20  N_MAIN_DB       
abb0: 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f     0x00000100  /
abc0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
abd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
abe0: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20  N_TEMP_DB       
abf0: 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f     0x00000200  /
ac00: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
ac10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
ac20: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20  N_TRANSIENT_DB  
ac30: 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f     0x00000400  /
ac40: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
ac50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
ac60: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20  N_MAIN_JOURNAL  
ac70: 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f     0x00000800  /
ac80: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
ac90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
aca0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20  N_TEMP_JOURNAL  
acb0: 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f     0x00001000  /
acc0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
acd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
ace0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20  N_SUBJOURNAL    
acf0: 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f     0x00002000  /
ad00: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
ad10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
ad20: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
ad30: 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f     0x00004000  /
ad40: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
ad50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
ad60: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20  N_NOMUTEX       
ad70: 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f     0x00008000  /
ad80: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
ad90: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
ada0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
adb0: 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20  N_FULLMUTEX     
adc0: 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f     0x00010000  /
add0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
ade0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
adf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
ae00: 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  N_SHAREDCACHE   
ae10: 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f     0x00020000  /
ae20: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
ae30: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
ae40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
ae50: 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20  N_PRIVATECACHE  
ae60: 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f     0x00040000  /
ae70: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
ae80: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
ae90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
aea0: 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  N_WAL           
aeb0: 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f     0x00080000  /
aec0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  * VFS only */../
aed0: 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20  * Reserved:     
aee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
aef0: 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a      0x00F00000 *
af00: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
af10: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63  F: Device Charac
af20: 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  teristics.**.** 
af30: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
af40: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
af50: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  d of the [sqlite
af60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
af70: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20   object returns 
af80: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
af90: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20   is a vector of 
afa0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
afb0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
afc0: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
afd0: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
afe0: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
aff0: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
b000: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
b010: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
b020: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
b030: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
b040: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
b050: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
b060: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
b070: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
b080: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
b090: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
b0a0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
b0b0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
b0c0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
b0d0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
b0e0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
b0f0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
b100: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
b110: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
b120: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
b130: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
b140: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
b150: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
b160: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
b170: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
b180: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
b190: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
b1a0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
b1b0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
b1c0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
b1d0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
b1e0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
b1f0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
b200: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
b210: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
b220: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
b230: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
b240: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
b250: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
b260: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54   to xWrite().  T
b270: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
b280: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
b290: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61  ITE property mea
b2a0: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72  ns that.** after
b2b0: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e   reboot followin
b2c0: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77  g a crash or pow
b2d0: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c  er loss, the onl
b2e0: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20  y bytes in a.** 
b2f0: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77  file that were w
b300: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70  ritten at the ap
b310: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20  plication level 
b320: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67  might have chang
b330: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61  ed.** and that a
b340: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65  djacent bytes, e
b350: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e  ven bytes within
b360: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72   the same sector
b370: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65   are.** guarante
b380: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67  ed to be unchang
b390: 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ed..*/.#define S
b3a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
b3b0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
b3c0: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
b3d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
b3e0: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
b3f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
b400: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
b410: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
b420: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
b430: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
b440: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
b450: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
b460: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
b470: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
b480: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
b490: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
b4a0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
b4b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
b4c0: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
b4d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
b4e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b4f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
b500: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
b510: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
b520: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
b530: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
b540: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
b550: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
b560: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
b570: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
b580: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
b590: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
b5a0: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
b5b0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
b5c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
b5d0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
b5e0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
b5f0: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
b600: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
b610: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
b620: 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69  0x00000800.#defi
b630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
b640: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
b650: 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30  ITE    0x0000100
b660: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
b670: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20  F: File Locking 
b680: 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  Levels.**.** SQL
b690: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
b6a0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
b6b0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
b6c0: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
b6d0: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
b6e0: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
b6f0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
b700: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
b710: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
b720: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
b730: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
b740: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
b750: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
b760: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
b770: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
b780: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
b790: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
b7a0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
b7b0: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
b7c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
b7d0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
b7e0: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
b7f0: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
b800: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a  ion Type Flags.*
b810: 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65  *.** When SQLite
b820: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79   invokes the xSy
b830: 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61  nc() method of a
b840: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
b850: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
b860: 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69   it uses a combi
b870: 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65  nation of.** the
b880: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
b890: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  s as the second 
b8a0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
b8b0: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  When the SQLITE_
b8c0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c  SYNC_DATAONLY fl
b8d0: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d  ag is used, it m
b8e0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  eans that the.**
b8f0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20   sync operation 
b900: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c  only needs to fl
b910: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73  ush data to mass
b920: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65   storage.  Inode
b930: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
b940: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73  need not be flus
b950: 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65  hed. If the lowe
b960: 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74  r four bits of t
b970: 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c  he flag.** equal
b980: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
b990: 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  MAL, that means 
b9a0: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73  to use normal fs
b9b0: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e  ync() semantics.
b9c0: 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72  .** If the lower
b9d0: 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c   four bits equal
b9e0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
b9f0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  L, that means.**
ba00: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58   to use Mac OS X
ba10: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
ba20: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
ba30: 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74  ()..**.** Do not
ba40: 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c   confuse the SQL
ba50: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
ba60: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
ba70: 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69  FULL flags.** wi
ba80: 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73  th the [PRAGMA s
ba90: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d  ynchronous]=NORM
baa0: 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73  AL and [PRAGMA s
bab0: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c  ynchronous]=FULL
bac0: 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54  .** settings.  T
bad0: 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20  he [synchronous 
bae0: 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e  pragma] determin
baf0: 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f  es when calls to
bb00: 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46   the.** xSync VF
bb10: 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61  S method occur a
bb20: 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f  nd applies unifo
bb30: 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  rmly across all 
bb40: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68  platforms..** Th
bb50: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
bb60: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
bb70: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20  SYNC_FULL flags 
bb80: 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a  determine how.**
bb90: 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69   energetic or ri
bba0: 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66  gorous or forcef
bbb0: 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72  ul the sync oper
bbc0: 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a  ations are and.*
bbd0: 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69  * only make a di
bbe0: 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20  fference on Mac 
bbf0: 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61  OSX for the defa
bc00: 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e  ult SQLite code.
bc10: 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79  .** (Third-party
bc20: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
bc30: 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  ions might also 
bc40: 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
bc50: 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
bc60: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
bc70: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
bc80: 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f  NC_FULL, but amo
bc90: 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74  ng the.** operat
bca0: 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69  ing systems nati
bcb0: 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62  vely supported b
bcc0: 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d  y SQLite, only M
bcd0: 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20  ac OSX.** cares 
bce0: 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72  about the differ
bcf0: 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e  ence.).*/.#defin
bd00: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
bd10: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30  RMAL        0x00
bd20: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
bd30: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20  TE_SYNC_FULL    
bd40: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64        0x00003.#d
bd50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
bd60: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20  C_DATAONLY      
bd70: 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43  0x00010../*.** C
bd80: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
bd90: 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20  rface Open File 
bda0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20  Handle.**.** An 
bdb0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
bdc0: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
bdd0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e   an open file in
bde0: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
bdf0: 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72  3_vfs | OS inter
be00: 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e  face layer].  In
be10: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
be20: 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  rface.** impleme
be30: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a  ntations will.**
be40: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73   want to subclas
be50: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79  s this object by
be60: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74   appending addit
be70: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20  ional fields.** 
be80: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73  for their own us
be90: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73  e.  The pMethods
bea0: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e   entry is a poin
beb0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
bec0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
bed0: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
bee0: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f  fines methods fo
bef0: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20  r performing.** 
bf00: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f  I/O operations o
bf10: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e  n the open file.
bf20: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
bf30: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
bf40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74  sqlite3_file;.st
bf50: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
bf60: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75  e {.  const stru
bf70: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
bf80: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b  thods *pMethods;
bf90: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
bfa0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f   an open file */
bfb0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
bfc0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
bfd0: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d  e File Virtual M
bfe0: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a  ethods Object.**
bff0: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
c000: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
c010: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
c020: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65   method populate
c030: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s an.** [sqlite3
c040: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f  _file] object (o
c050: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79  r, more commonly
c060: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  , a subclass of 
c070: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
c080: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69  file] object) wi
c090: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  th a pointer to 
c0a0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
c0b0: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54  his object..** T
c0c0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
c0d0: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75  es the methods u
c0e0: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  sed to perform v
c0f0: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e  arious operation
c100: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65  s.** against the
c110: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65   open file repre
c120: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73  sented by the [s
c130: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
c140: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ect..**.** If th
c150: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
c160: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74  Open] method set
c170: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  s the sqlite3_fi
c180: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
c190: 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e  ent .** to a non
c1a0: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
c1b0: 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
c1c0: 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73  io_methods.xClos
c1d0: 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20  e method.** may 
c1e0: 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20  be invoked even 
c1f0: 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  if the [sqlite3_
c200: 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72  vfs.xOpen] repor
c210: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c  ted that it fail
c220: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79  ed.  The.** only
c230: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20   way to prevent 
c240: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65  a call to xClose
c250: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
c260: 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  led [sqlite3_vfs
c270: 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f  .xOpen].** is fo
c280: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  r the [sqlite3_v
c290: 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74  fs.xOpen] to set
c2a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
c2b0: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
c2c0: 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  nt.** to NULL..*
c2d0: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
c2e0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63  rgument to xSync
c2f0: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b   may be one of [
c300: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
c310: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  AL] or.** [SQLIT
c320: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54  E_SYNC_FULL].  T
c330: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20  he first choice 
c340: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73  is the normal fs
c350: 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65  ync()..** The se
c360: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61  cond choice is a
c370: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
c380: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b  fullsync.  The [
c390: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
c3a0: 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61  ONLY].** flag ma
c3b0: 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20  y be ORed in to 
c3c0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e  indicate that on
c3d0: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74  ly the data of t
c3e0: 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e  he file.** and n
c3f0: 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65  ot its inode nee
c400: 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e  ds to be synced.
c410: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67  .**.** The integ
c420: 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f  er values to xLo
c430: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
c440: 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a  () are one of.**
c450: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
c460: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
c470: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
c480: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
c490: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
c4a0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a  LOCK_RESERVED],.
c4b0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
c4c0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
c4d0: 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
c4e0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
c4f0: 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78  ]..** </ul>.** x
c500: 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73  Lock() increases
c510: 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f   the lock. xUnlo
c520: 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74  ck() decreases t
c530: 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20  he lock..** The 
c540: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
c550: 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63  ck() method chec
c560: 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64  ks whether any d
c570: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
c580: 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e  on,.** either in
c590: 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72   this process or
c5a0: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70   in some other p
c5b0: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69  rocess, is holdi
c5c0: 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a  ng a RESERVED,.*
c5d0: 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58  * PENDING, or EX
c5e0: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20  CLUSIVE lock on 
c5f0: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65  the file.  It re
c600: 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66  turns true.** if
c610: 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69   such a lock exi
c620: 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74  sts and false ot
c630: 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54  herwise..**.** T
c640: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
c650: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
c660: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
c670: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
c680: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
c690: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
c6a0: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
c6b0: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
c6c0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
c6d0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
c6e0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
c6f0: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
c700: 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69  ument is an.** i
c710: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
c720: 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
c730: 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  nt is a generic 
c740: 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64  pointer intended
c750: 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20   to.** point to 
c760: 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  a structure that
c770: 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67   may contain arg
c780: 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20  uments or space 
c790: 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77  in which to.** w
c7a0: 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75  rite return valu
c7b0: 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75  es.  Potential u
c7c0: 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e  ses for xFileCon
c7d0: 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a  trol() might be.
c7e0: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20  ** functions to 
c7f0: 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20  enable blocking 
c800: 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f  locks with timeo
c810: 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74  uts, to change t
c820: 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74  he.** locking st
c830: 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d  rategy (for exam
c840: 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66  ple to use dot-f
c850: 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69  ile locks), to i
c860: 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20  nquire.** about 
c870: 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20  the status of a 
c880: 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61  lock, or to brea
c890: 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20  k stale locks.  
c8a0: 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f  The SQLite.** co
c8b0: 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20  re reserves all 
c8c0: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61  opcodes less tha
c8d0: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77  n 100 for its ow
c8e0: 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c  n use..** A [SQL
c8f0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
c900: 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  ATE | list of op
c910: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
c920: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
c930: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
c940: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
c950: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
c960: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
c970: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a  ld use opcodes.*
c980: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
c990: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
c9a0: 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c  licts.  VFS impl
c9b0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
c9c0: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
c9d0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66  LITE_NOTFOUND] f
c9e0: 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  or file control 
c9f0: 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65  opcodes that the
ca00: 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f  y do not.** reco
ca10: 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  gnize..**.** The
ca20: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
ca30: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
ca40: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
ca50: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
ca60: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
ca70: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
ca80: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
ca90: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
caa0: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
cab0: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
cac0: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
cad0: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
cae0: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
caf0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
cb00: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
cb10: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
cb20: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
cb30: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
cb40: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
cb50: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
cb60: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
cb70: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
cb80: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
cb90: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
cba0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
cbb0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
cbc0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
cbd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
cbe0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
cbf0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
cc00: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
cc10: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
cc20: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
cc30: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
cc40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
cc50: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
cc60: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
cc70: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
cc80: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
cc90: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
cca0: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
ccb0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
ccc0: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  NTIAL].** </ul>.
ccd0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
cce0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
ccf0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
cd00: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
cd10: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
cd20: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
cd30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
cd40: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
cd50: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
cd60: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
cd70: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
cd80: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
cd90: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
cda0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
cdb0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
cdc0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
cdd0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
cde0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
cdf0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
ce00: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
ce10: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
ce20: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
ce30: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
ce40: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
ce50: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
ce60: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
ce70: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
ce80: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
ce90: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
cea0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
ceb0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
cec0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
ced0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
cee0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
cef0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
cf00: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a  to xWrite()..**.
cf10: 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65  ** If xRead() re
cf20: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45  turns SQLITE_IOE
cf30: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74  RR_SHORT_READ it
cf40: 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a   must also fill.
cf50: 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64  ** in the unread
cf60: 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65   portions of the
cf70: 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72   buffer with zer
cf80: 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a  os.  A VFS that.
cf90: 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f  ** fails to zero
cfa0: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
cfb0: 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20  s might seem to 
cfc0: 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a  work.  However,.
cfd0: 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65  ** failure to ze
cfe0: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
cff0: 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  ads will eventua
d000: 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64  lly lead to.** d
d010: 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
d020: 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
d030: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
d040: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
d050: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
d060: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
d070: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
d080: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
d090: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
d0a0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
d0b0: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
d0c0: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
d0d0: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
d0e0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
d0f0: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71  int (*xWrite)(sq
d100: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e  lite3_file*, con
d110: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  st void*, int iA
d120: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
d130: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
d140: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c  (*xTruncate)(sql
d150: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
d160: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b  te3_int64 size);
d170: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
d180: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
d190: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
d1a0: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71   (*xFileSize)(sq
d1b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
d1c0: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a  ite3_int64 *pSiz
d1d0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63  e);.  int (*xLoc
d1e0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
d1f0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
d200: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33  xUnlock)(sqlite3
d210: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
d220: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65  int (*xCheckRese
d230: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65  rvedLock)(sqlite
d240: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52  3_file*, int *pR
d250: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
d260: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71  xFileControl)(sq
d270: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
d280: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29   op, void *pArg)
d290: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f  ;.  int (*xSecto
d2a0: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  rSize)(sqlite3_f
d2b0: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
d2c0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
d2d0: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66  stics)(sqlite3_f
d2e0: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  ile*);.  /* Meth
d2f0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
d300: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
d310: 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68  1 */.  int (*xSh
d320: 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  mMap)(sqlite3_fi
d330: 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e  le*, int iPg, in
d340: 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69  t pgsz, int, voi
d350: 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20  d volatile**);. 
d360: 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29   int (*xShmLock)
d370: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
d380: 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20  int offset, int 
d390: 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  n, int flags);. 
d3a0: 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72   void (*xShmBarr
d3b0: 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ier)(sqlite3_fil
d3c0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  e*);.  int (*xSh
d3d0: 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f  mUnmap)(sqlite3_
d3e0: 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74  file*, int delet
d3f0: 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74  eFlag);.  /* Met
d400: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
d410: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
d420: 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74   2 */.  /* Addit
d430: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61  ional methods ma
d440: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
d450: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f  ture releases */
d460: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
d470: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69  REF: Standard Fi
d480: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64  le Control Opcod
d490: 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  es.**.** These i
d4a0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
d4b0: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72   are opcodes for
d4c0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
d4d0: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  l method.** of t
d4e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
d4f0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61  ethods] object a
d500: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  nd for the [sqli
d510: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
d520: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
d530: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
d540: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
d550: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
d560: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
d570: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
d580: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
d590: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
d5a0: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
d5b0: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
d5c0: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
d5d0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
d5e0: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
d5f0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
d600: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
d610: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
d620: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
d630: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
d640: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
d650: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
d660: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
d670: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
d680: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
d690: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
d6a0: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f  ng testing and o
d6b0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
d6c0: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
d6d0: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73  QLITE_TEST.** is
d6e0: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c   defined..** <ul
d6f0: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  >.** <li>[[SQLIT
d700: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
d710: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
d720: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
d730: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
d740: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
d750: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
d760: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
d770: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
d780: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
d790: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
d7a0: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
d7b0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
d7c0: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
d7d0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
d7e0: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
d7f0: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
d800: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
d810: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
d820: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
d830: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
d840: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
d850: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
d860: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
d870: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
d880: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
d890: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
d8a0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
d8b0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
d8c0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
d8d0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
d8e0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
d8f0: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
d900: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
d910: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
d920: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
d930: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
d940: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
d950: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
d960: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
d970: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
d980: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
d990: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
d9a0: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
d9b0: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
d9c0: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
d9d0: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
d9e0: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
d9f0: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
da00: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
da10: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
da20: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
da30: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
da40: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
da50: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
da60: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
da70: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
da80: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
da90: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
daa0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
dab0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
dac0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
dad0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
dae0: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
daf0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
db00: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
db10: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
db20: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
db30: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
db40: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
db50: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
db60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
db70: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63  e_control()] doc
db80: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  umentation for.*
db90: 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
dba0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
dbb0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
dbc0: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
dbd0: 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49  ].** ^(The [SQLI
dbe0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
dbf0: 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73  ITTED] opcode is
dc00: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
dc10: 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69  nally by.** SQLi
dc20: 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61  te and sent to a
dc30: 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63  ll VFSes in plac
dc40: 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74  e of a call to t
dc50: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a  he xSync method.
dc60: 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  ** when the data
dc70: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
dc80: 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  has [PRAGMA sync
dc90: 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20  hronous] set to 
dca0: 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73  OFF.)^.** Some s
dcb0: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
dcc0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
dcd0: 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70  l in order to op
dce0: 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a  erate correctly.
dcf0: 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20  ** when [PRAGMA 
dd00: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52  synchronous | PR
dd10: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
dd20: 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75  =OFF] is set, bu
dd30: 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73  t most .** VFSes
dd40: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
dd50: 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f  s signal and sho
dd60: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
dd70: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
dd80: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
dd90: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
dda0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
ddb0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
ddc0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73  his.** opcode as
ddd0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
dde0: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
ddf0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
de00: 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20  alized VFSes.** 
de10: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
de20: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
de30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
de40: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a  IN32_AV_RETRY]].
de50: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
de60: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
de70: 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETRY] opcode is 
de80: 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
de90: 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72  e automatic.** r
dea0: 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20  etry counts and 
deb0: 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65  intervals for ce
dec0: 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f  rtain disk I/O o
ded0: 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68  perations for th
dee0: 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46  e.** windows [VF
def0: 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  S] in order to p
df00: 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73  rovide robustnes
df10: 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63  s in the presenc
df20: 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72  e of.** anti-vir
df30: 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79  us programs.  By
df40: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69   default, the wi
df50: 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72  ndows VFS will r
df60: 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a  etry file read,.
df70: 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61  ** file write, a
df80: 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f  nd file delete o
df90: 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20  perations up to 
dfa0: 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61  10 times, with a
dfb0: 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20   delay.** of 25 
dfc0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66  milliseconds bef
dfd0: 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65  ore the first re
dfe0: 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65  try and with the
dff0: 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e   delay increasin
e000: 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74  g.** by an addit
e010: 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65  ional 25 millise
e020: 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20  conds with each 
e030: 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79  subsequent retry
e040: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
e050: 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74  e allows these t
e060: 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65  wo values (10 re
e070: 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c  tries and 25 mil
e080: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c  liseconds of del
e090: 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a  ay).** to be adj
e0a0: 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75  usted.  The valu
e0b0: 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66  es are changed f
e0c0: 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20  or all database 
e0d0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77  connections.** w
e0e0: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70  ithin the same p
e0f0: 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67  rocess.  The arg
e100: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
e110: 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f  er to an array o
e120: 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72  f two.** integer
e130: 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73  s where the firs
e140: 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20  t integer i the 
e150: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20  new retry count 
e160: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  and the second.*
e170: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65  * integer is the
e180: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68   delay.  If eith
e190: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65  er integer is ne
e1a0: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
e1b0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e   setting.** is n
e1c0: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69  ot changed but i
e1d0: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72  nstead the prior
e1e0: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73   value of that s
e1f0: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65  etting is writte
e200: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72  n.** into the ar
e210: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77  ray entry, allow
e220: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20  ing the current 
e230: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74  retry settings t
e240: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67  o be.** interrog
e250: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61  ated.  The zDbNa
e260: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
e270: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  ignored..**.** <
e280: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
e290: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a  L_PERSIST_WAL]].
e2a0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
e2b0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
e2c0: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  L] opcode is use
e2d0: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
e2e0: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
e2f0: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65  ent [WAL | Write
e300: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74   Ahead Log] sett
e310: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ing.  By default
e320: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a  , the auxiliary.
e330: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c  ** write ahead l
e340: 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  og and shared me
e350: 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20  mory files used 
e360: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  for transaction 
e370: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61  control.** are a
e380: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
e390: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61  eted when the la
e3a0: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  test connection 
e3b0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
e3c0: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74  ** closes.  Sett
e3d0: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57  ing persistent W
e3e0: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74  AL mode causes t
e3f0: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65  hose files to pe
e400: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63  rsist after.** c
e410: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e  lose.  Persistin
e420: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75  g the files is u
e430: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72  seful when other
e440: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20   processes that 
e450: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77  do not.** have w
e460: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20  rite permission 
e470: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  on the directory
e480: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
e490: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
e4a0: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68  nt.** to read th
e4b0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
e4c0: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20   as the WAL and 
e4d0: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
e4e0: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a  les must exist.*
e4f0: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74  * in order for t
e500: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62  he database to b
e510: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  e readable.  The
e520: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
e530: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
e540: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
e550: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
e560: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
e570: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
e580: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
e590: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
e5a0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57  ble persistent W
e5b0: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  AL mode or 1 to 
e5c0: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  enable persisten
e5d0: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20  t.** WAL mode.  
e5e0: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
e5f0: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
e600: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
e610: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
e620: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65   WAL persistence
e630: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
e640: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
e650: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
e660: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
e670: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
e680: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
e690: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
e6a0: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
e6b0: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
e6c0: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d  tent "powersafe-
e6d0: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50  overwrite" or "P
e6e0: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54  SOW" setting.  T
e6f0: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a  he PSOW setting.
e700: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  ** determines th
e710: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  e [SQLITE_IOCAP_
e720: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
e730: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a  ITE] bit of the.
e740: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63  ** xDeviceCharac
e750: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
e760: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  s. The fourth pa
e770: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
e780: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
e790: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
e7a0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
e7b0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
e7c0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
e7d0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
e7e0: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64  o disable zero-d
e7f0: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20  amage mode or 1 
e800: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64  to enable zero-d
e810: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20  amage.** mode.  
e820: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
e830: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
e840: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
e850: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
e860: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
e870: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
e880: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
e890: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  NTL_OVERWRITE]].
e8a0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
e8b0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
e8c0: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
e8d0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
e8e0: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
e8f0: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
e900: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
e910: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
e920: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
e930: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
e940: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
e950: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
e960: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
e970: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
e980: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
e990: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
e9a0: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
e9b0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
e9c0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
e9d0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
e9e0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
e9f0: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
ea00: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
ea10: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20  the names of.** 
ea20: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74  all [VFSes] in t
ea30: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54  he VFS stack.  T
ea40: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20  he names are of 
ea50: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e  all VFS shims an
ea60: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62  d the.** final b
ea70: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20  ottom-level VFS 
ea80: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  are written into
ea90: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
eaa0: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
eab0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
eac0: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73   the result is s
ead0: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61  tored in the cha
eae0: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74  r* variable.** t
eaf0: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70  hat the fourth p
eb00: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
eb10: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
eb20: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a  l()] points to..
eb30: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73  ** The caller is
eb40: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
eb50: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
eb60: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20  ory when done.  
eb70: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66  As with.** all f
eb80: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69  ile-control acti
eb90: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f  ons, there is no
eba0: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
ebb0: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c  this will actual
ebc0: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e  ly.** do anythin
ebd0: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75  g.  Callers shou
ebe0: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68  ld initialize th
ebf0: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
ec00: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   to a NULL.** po
ec10: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68  inter in case th
ec20: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
ec30: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
ec40: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63  ed.  This file-c
ec50: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74  ontrol.** is int
ec60: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f  ended for diagno
ec70: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a  stic use only..*
ec80: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ec90: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d  E_FCNTL_PRAGMA]]
eca0: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20  .** ^Whenever a 
ecb0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
ecc0: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e  nt is parsed, an
ecd0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
ece0: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20  RAGMA] .** file 
ecf0: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20  control is sent 
ed00: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c  to the open [sql
ed10: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
ed20: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  t corresponding.
ed30: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ** to the databa
ed40: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68  se file to which
ed50: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74   the pragma stat
ed60: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54  ement refers. ^T
ed70: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
ed80: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  o the [SQLITE_FC
ed90: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
eda0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61   control is an a
edb0: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74  rray of.** point
edc0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28  ers to strings (
edd0: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68  char**) in which
ede0: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d   the second elem
edf0: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79  ent of the array
ee00: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
ee10: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e  of the pragma an
ee20: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d  d the third elem
ee30: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ent is the argum
ee40: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72  ent to the.** pr
ee50: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20  agma or NULL if 
ee60: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e  the pragma has n
ee70: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  o argument.  ^Th
ee80: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e  e handler for an
ee90: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
eea0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
eeb0: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f  ontrol can optio
eec0: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66  nally make the f
eed0: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  irst element.** 
eee0: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72  of the char** ar
eef0: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20  gument point to 
ef00: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  a string obtaine
ef10: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
ef20: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72  mprintf()].** or
ef30: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
ef40: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20  and that string 
ef50: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
ef60: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72  result of the pr
ef70: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65  agma or.** the e
ef80: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20  rror message if 
ef90: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73  the pragma fails
efa0: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51  . ^If the.** [SQ
efb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
efc0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
efd0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
efe0: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20  NOTFOUND], then 
eff0: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47  normal .** [PRAG
f000: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63  MA] processing c
f010: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74  ontinues.  ^If t
f020: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
f030: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
f040: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
f050: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
f060: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73  en the parser as
f070: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
f080: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65  * VFS has handle
f090: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73  d the PRAGMA its
f0a0: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73  elf and the pars
f0b0: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e  er generates a n
f0c0: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64  o-op.** prepared
f0d0: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66   statement.  ^If
f0e0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
f0f0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
f100: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a  control returns.
f110: 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f  ** any result co
f120: 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  de other than [S
f130: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51  QLITE_OK] or [SQ
f140: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
f150: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  that means.** th
f160: 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75  at the VFS encou
f170: 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20  ntered an error 
f180: 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74  while handling t
f190: 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20  he [PRAGMA] and 
f1a0: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69  the.** compilati
f1b0: 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41  on of the PRAGMA
f1c0: 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65   fails with an e
f1d0: 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c  rror.  ^The [SQL
f1e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
f1f0: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
f200: 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20  l occurs at the 
f210: 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61  beginning of pra
f220: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  gma statement an
f230: 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a  alysis and so.**
f240: 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f   it is able to o
f250: 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e  verride built-in
f260: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
f270: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ents..**.** <li>
f280: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  [[SQLITE_FCNTL_B
f290: 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20  USYHANDLER]].** 
f2a0: 5e 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72  ^This file-contr
f2b0: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ol may be invoke
f2c0: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74  d by SQLite on t
f2d0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
f2e0: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74   handle.** short
f2f0: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f  ly after it is o
f300: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  pened in order t
f310: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74  o provide a cust
f320: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65  om VFS with acce
f330: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e  ss.** to the con
f340: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61  nections busy-ha
f350: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  ndler callback. 
f360: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
f370: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a  of type (void **
f380: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20  ).** - an array 
f390: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20  of two (void *) 
f3a0: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73  values. The firs
f3b0: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61  t (void *) actua
f3c0: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f  lly points.** to
f3d0: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
f3e0: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69  ype (int (*)(voi
f3f0: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20  d *)). In order 
f400: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f  to invoke the co
f410: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73  nnections.** bus
f420: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20  y-handler, this 
f430: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
f440: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
f450: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64  the second (void
f460: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72   *) in.** the ar
f470: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ray as the only 
f480: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20  argument. If it 
f490: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
f4a0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61  , then the opera
f4b0: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
f4c0: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74  e retried. If it
f4d0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
f4e0: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68  he custom VFS sh
f4f0: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65  ould abandon the
f500: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72  .** current oper
f510: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
f520: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
f530: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a  TEMPFILENAME]].*
f540: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63  * ^Application c
f550: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 66  an invoke this f
f560: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 74 6f 20 68  ile-control to h
f570: 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72  ave SQLite gener
f580: 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61  ate a.** tempora
f590: 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e  ry filename usin
f5a0: 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
f5b0: 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c  ithm that is fol
f5c0: 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74  lowed to generat
f5d0: 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
f5e0: 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d  ilenames for TEM
f5f0: 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68  P tables and oth
f600: 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73  er internal uses
f610: 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65  .  The.** argume
f620: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  nt should be a c
f630: 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  har** which will
f640: 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20   be filled with 
f650: 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
f660: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
f670: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
f680: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
f690: 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65  c()].  The calle
f6a0: 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f  r should.** invo
f6b0: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
f6c0: 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c  ()] on the resul
f6d0: 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d  t to avoid a mem
f6e0: 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20  ory leak..**.** 
f6f0: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
f700: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
f710: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
f720: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
f730: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
f740: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20  ROXYFILE        
f750: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
f760: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52  QLITE_SET_LOCKPR
f770: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20  OXYFILE         
f780: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
f790: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
f7a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
f7b0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
f7c0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
f7d0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
f7e0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
f7f0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
f800: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
f810: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
f820: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
f830: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
f840: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
f850: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
f860: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
f870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f880: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
f890: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
f8a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
f8b0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
f8c0: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
f8d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
f8e0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
f8f0: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
f900: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
f910: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
f920: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
f930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
f940: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
f950: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
f960: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
f970: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
f980: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
f990: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
f9a0: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
f9b0: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
f9c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
f9d0: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
f9e0: 20 20 20 20 20 20 31 36 0a 0a 2f 2a 0a 2a 2a 20        16../*.** 
f9f0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
fa00: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
fa10: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
fa20: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
fa30: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
fa40: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
fa50: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
fa60: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
fa70: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
fa80: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
fa90: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
faa0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
fab0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
fac0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
fad0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
fae0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
faf0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
fb00: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
fb10: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
fb20: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
fb30: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
fb40: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
fb50: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
fb60: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
fb70: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
fb80: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
fb90: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
fba0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
fbb0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
fbc0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
fbd0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
fbe0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
fbf0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
fc00: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
fc10: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
fc20: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
fc30: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
fc40: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
fc50: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
fc60: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
fc70: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
fc80: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
fc90: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
fca0: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
fcb0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
fcc0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
fcd0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
fce0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
fcf0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
fd00: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
fd10: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
fd20: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
fd30: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
fd40: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
fd50: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
fd60: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
fd70: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
fd80: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
fd90: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
fda0: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
fdb0: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
fdc0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
fdd0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
fde0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
fdf0: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
fe00: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
fe10: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
fe20: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
fe30: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
fe40: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
fe50: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
fe60: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
fe70: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
fe80: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
fe90: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
fea0: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
feb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
fec0: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
fed0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
fee0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
fef0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
ff00: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
ff10: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
ff20: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
ff30: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
ff40: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
ff50: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
ff60: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
ff70: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
ff80: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
ff90: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
ffa0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
ffb0: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
ffc0: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
ffd0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
ffe0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
fff0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
10000 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
10010 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
10020 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
10030 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
10040 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
10050 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
10060 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
10070 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
10080 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
10090 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
100a0 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
100b0 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
100c0 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
100d0 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
100e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
100f0 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
10100 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
10110 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
10120 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
10130 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
10140 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
10150 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
10160 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
10170 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
10180 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
10190 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
101a0 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
101b0 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
101c0 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
101d0 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
101e0 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
101f0 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
10200 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
10210 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
10220 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
10230 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
10240 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
10250 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
10260 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
10270 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
10280 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
10290 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
102a0 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
102b0 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
102c0 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
102d0 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
102e0 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
102f0 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
10300 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
10310 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
10320 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
10330 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
10340 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
10350 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
10360 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
10370 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
10380 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
10390 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
103a0 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
103b0 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
103c0 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
103d0 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
103e0 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
103f0 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
10400 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
10410 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
10420 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
10430 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
10440 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
10450 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
10460 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
10470 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
10480 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
10490 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
104a0 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
104b0 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
104c0 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
104d0 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
104e0 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
104f0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
10500 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
10510 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
10520 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
10530 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
10540 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
10550 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
10560 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
10570 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
10580 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
10590 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
105a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
105b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
105c0 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
105d0 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
105e0 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
105f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
10600 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
10610 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
10620 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
10630 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
10640 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
10650 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
10660 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
10670 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
10680 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
10690 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
106a0 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
106b0 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
106c0 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
106d0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
106e0 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
106f0 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
10700 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
10710 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
10720 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
10730 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
10740 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
10750 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
10760 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
10770 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
10780 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
10790 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
107a0 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
107b0 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
107c0 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
107d0 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
107e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
107f0 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
10800 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
10810 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
10820 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
10830 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
10840 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
10850 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
10860 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
10870 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
10880 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
10890 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
108a0 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
108b0 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
108c0 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
108d0 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
108e0 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
108f0 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
10900 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
10910 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
10920 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
10930 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
10940 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
10950 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
10960 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
10970 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
10980 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
10990 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
109a0 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
109b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
109c0 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
109d0 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
109e0 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
109f0 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
10a00 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
10a10 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
10a20 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
10a30 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
10a40 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
10a50 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
10a60 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
10a70 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
10a80 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
10a90 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
10aa0 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
10ab0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
10ac0 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
10ad0 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
10ae0 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
10af0 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
10b00 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
10b10 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
10b20 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
10b30 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
10b40 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
10b50 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
10b60 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
10b70 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
10b80 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
10b90 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
10ba0 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
10bb0 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
10bc0 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
10bd0 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
10be0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
10bf0 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
10c00 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
10c10 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
10c20 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
10c30 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
10c40 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
10c50 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
10c60 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
10c70 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
10c80 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
10c90 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
10ca0 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
10cb0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
10cc0 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
10cd0 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
10ce0 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
10cf0 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
10d00 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
10d10 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
10d20 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
10d30 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
10d40 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
10d50 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
10d60 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
10d70 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
10d80 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
10d90 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
10da0 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
10db0 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
10dc0 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
10dd0 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
10de0 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
10df0 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
10e00 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
10e10 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
10e20 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
10e30 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
10e40 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
10e50 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
10e60 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
10e70 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
10e80 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
10e90 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
10ea0 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
10eb0 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
10ec0 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
10ed0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
10ee0 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
10ef0 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
10f00 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
10f10 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
10f20 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
10f30 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
10f40 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
10f50 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
10f60 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
10f70 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
10f80 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
10f90 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
10fa0 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
10fb0 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
10fc0 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
10fd0 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
10fe0 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
10ff0 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
11000 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
11010 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
11020 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
11030 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
11040 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
11050 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
11060 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
11070 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
11080 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
11090 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
110a0 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
110b0 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
110c0 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
110d0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
110e0 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
110f0 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
11100 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
11110 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
11120 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
11130 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
11140 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
11150 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
11160 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
11170 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
11180 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
11190 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
111a0 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
111b0 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
111c0 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
111d0 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
111e0 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
111f0 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
11200 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
11210 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
11220 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
11230 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
11240 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
11250 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
11260 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
11270 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
11280 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
11290 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
112a0 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
112b0 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
112c0 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
112d0 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
112e0 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
112f0 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
11300 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
11310 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
11320 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
11330 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
11340 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
11350 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
11360 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
11370 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
11380 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
11390 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
113a0 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
113b0 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
113c0 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
113d0 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
113e0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
113f0 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
11400 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
11410 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
11420 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
11430 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
11440 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
11450 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
11460 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
11470 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
11480 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
11490 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
114a0 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
114b0 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
114c0 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
114d0 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
114e0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
114f0 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
11500 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
11510 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
11520 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
11530 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
11540 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
11550 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
11560 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
11570 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
11580 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
11590 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
115a0 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
115b0 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
115c0 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
115d0 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
115e0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
115f0 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
11600 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
11610 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
11620 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
11630 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
11640 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
11650 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
11660 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
11670 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
11680 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
11690 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
116a0 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
116b0 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
116c0 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
116d0 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
116e0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
116f0 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
11700 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
11710 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
11720 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
11730 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
11740 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
11750 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
11760 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
11770 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
11780 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
11790 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
117a0 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
117b0 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
117c0 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
117d0 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
117e0 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
117f0 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
11800 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
11810 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
11820 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
11830 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
11840 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
11850 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
11860 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
11870 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
11880 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
11890 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
118a0 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
118b0 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
118c0 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
118d0 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
118e0 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
118f0 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
11900 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
11910 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
11920 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
11930 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
11940 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
11950 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
11960 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
11970 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
11980 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
11990 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
119a0 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
119b0 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
119c0 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
119d0 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
119e0 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
119f0 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
11a00 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
11a10 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
11a20 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
11a30 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
11a40 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
11a50 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
11a60 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
11a70 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
11a80 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
11a90 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
11aa0 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
11ab0 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
11ac0 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
11ad0 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
11ae0 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
11af0 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
11b00 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
11b10 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
11b20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
11b30 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
11b40 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
11b50 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
11b60 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
11b70 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
11b80 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
11b90 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
11ba0 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
11bb0 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
11bc0 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
11bd0 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
11be0 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
11bf0 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
11c00 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
11c10 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
11c20 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
11c30 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
11c40 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
11c50 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
11c60 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
11c70 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
11c80 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
11c90 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
11ca0 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
11cb0 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
11cc0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
11cd0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
11ce0 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
11cf0 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
11d00 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
11d10 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
11d20 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
11d30 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
11d40 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
11d50 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
11d60 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
11d70 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
11d80 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
11d90 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
11da0 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
11db0 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
11dc0 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
11dd0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
11de0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
11df0 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
11e00 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
11e10 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
11e20 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
11e30 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
11e40 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
11e50 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
11e60 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
11e70 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
11e80 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
11e90 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
11ea0 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
11eb0 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
11ec0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
11ed0 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
11ee0 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
11ef0 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
11f00 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
11f10 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
11f20 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
11f30 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
11f40 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
11f50 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
11f60 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
11f70 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
11f80 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
11f90 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
11fa0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
11fb0 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
11fc0 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
11fd0 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
11fe0 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
11ff0 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
12000 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
12010 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
12020 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
12030 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
12040 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
12050 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
12060 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
12070 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
12080 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
12090 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
120a0 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
120b0 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
120c0 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
120d0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
120e0 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
120f0 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
12100 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
12110 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
12120 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
12130 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
12140 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
12150 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
12160 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
12170 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
12180 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
12190 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
121a0 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
121b0 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
121c0 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
121d0 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
121e0 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
121f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
12200 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
12210 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
12220 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
12230 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
12240 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
12250 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
12260 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
12270 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
12280 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
12290 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
122a0 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
122b0 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
122c0 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
122d0 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
122e0 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
122f0 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
12300 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
12310 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
12320 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
12330 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
12340 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
12350 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
12360 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
12370 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
12380 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
12390 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
123a0 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
123b0 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
123c0 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
123d0 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
123e0 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
123f0 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
12400 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
12410 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
12420 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
12430 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
12440 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
12450 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
12460 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
12470 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
12480 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
12490 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
124a0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
124b0 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
124c0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
124d0 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
124e0 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
124f0 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
12500 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
12510 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
12520 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
12530 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
12540 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
12550 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
12560 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
12570 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
12580 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
12590 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
125a0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
125b0 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
125c0 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
125d0 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
125e0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
125f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
12600 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
12610 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
12620 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12630 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
12640 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
12650 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
12660 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
12670 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
12680 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
12690 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
126a0 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
126b0 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
126c0 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
126d0 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
126e0 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
126f0 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
12700 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
12710 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
12720 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
12730 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
12740 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
12750 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
12760 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
12770 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
12780 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
12790 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
127a0 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
127b0 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
127c0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
127d0 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
127e0 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
127f0 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
12800 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
12810 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
12820 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
12830 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
12840 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
12850 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
12860 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
12870 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
12880 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
12890 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
128a0 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
128b0 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
128c0 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
128d0 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
128e0 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
128f0 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
12900 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
12910 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
12920 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
12930 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
12940 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
12950 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
12960 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
12970 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
12980 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
12990 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
129a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
129b0 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
129c0 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
129d0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
129e0 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
129f0 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
12a00 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
12a10 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
12a20 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
12a30 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
12a40 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
12a50 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
12a60 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
12a70 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
12a80 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
12a90 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
12aa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12ab0 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
12ac0 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
12ad0 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
12ae0 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
12af0 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
12b00 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
12b10 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
12b20 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
12b30 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
12b40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
12b50 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
12b60 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
12b70 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
12b80 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
12b90 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
12ba0 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
12bb0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
12bc0 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
12bd0 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
12be0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
12bf0 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
12c00 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
12c10 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
12c20 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
12c30 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
12c40 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
12c50 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
12c60 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
12c70 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
12c80 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
12c90 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
12ca0 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
12cb0 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
12cc0 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
12cd0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
12ce0 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
12cf0 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
12d00 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
12d10 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
12d20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
12d30 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12d40 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
12d50 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
12d60 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
12d70 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
12d80 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
12d90 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
12da0 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
12db0 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
12dc0 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
12dd0 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
12de0 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
12df0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
12e00 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12e10 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
12e20 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
12e30 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
12e40 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
12e50 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
12e60 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
12e70 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
12e80 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
12e90 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
12ea0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12eb0 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
12ec0 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
12ed0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
12ee0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
12ef0 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
12f00 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
12f10 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
12f20 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12f30 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
12f40 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
12f50 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12f60 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
12f70 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
12f80 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
12f90 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
12fa0 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
12fb0 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
12fc0 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
12fd0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
12fe0 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
12ff0 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
13000 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
13010 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
13020 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
13030 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
13040 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
13050 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
13060 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
13070 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
13080 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
13090 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
130a0 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
130b0 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
130c0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
130d0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
130e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
130f0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
13100 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
13110 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
13120 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
13130 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
13140 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
13150 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
13160 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
13170 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
13180 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
13190 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
131a0 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
131b0 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
131c0 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
131d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
131e0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
131f0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
13200 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
13210 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
13220 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
13230 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
13240 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
13250 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
13260 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
13270 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
13280 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
13290 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
132a0 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
132b0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
132c0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
132d0 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
132e0 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
132f0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
13300 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
13310 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
13320 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
13330 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
13340 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
13350 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
13360 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
13370 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
13380 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13390 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
133a0 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
133b0 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
133c0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
133d0 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
133e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
133f0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
13400 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
13410 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
13420 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
13430 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
13440 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
13450 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
13460 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
13470 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
13480 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
13490 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
134a0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
134b0 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
134c0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
134d0 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
134e0 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
134f0 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
13500 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
13510 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
13520 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
13530 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
13540 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
13550 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
13560 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
13570 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13580 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
13590 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
135a0 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
135b0 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
135c0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
135d0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
135e0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
135f0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
13600 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
13610 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
13620 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
13630 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
13640 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
13650 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
13660 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
13670 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
13680 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
13690 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
136a0 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
136b0 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
136c0 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
136d0 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
136e0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
136f0 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
13700 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
13710 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
13720 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
13730 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
13740 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
13750 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
13760 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
13770 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
13780 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
13790 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
137a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
137b0 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
137c0 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
137d0 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
137e0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
137f0 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
13800 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
13810 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
13820 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
13830 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
13840 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
13850 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
13860 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
13870 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
13880 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
13890 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
138a0 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
138b0 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
138c0 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
138d0 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
138e0 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
138f0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
13900 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
13910 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
13920 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
13930 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
13940 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
13950 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
13960 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
13970 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
13980 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
13990 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
139a0 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
139b0 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
139c0 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
139d0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
139e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
139f0 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
13a00 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
13a10 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
13a20 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
13a30 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
13a40 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
13a50 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
13a60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
13a70 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
13a80 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
13a90 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
13aa0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
13ab0 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
13ac0 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
13ad0 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
13ae0 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49  failure..*/.SQLI
13af0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
13b00 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
13b10 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
13b20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
13b30 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  down(void);.SQLI
13b40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
13b50 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
13b60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
13b70 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
13b80 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
13b90 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
13ba0 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
13bb0 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65  ibrary.**.** The
13bc0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
13bd0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
13be0 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
13bf0 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
13c00 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
13c10 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
13c20 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
13c30 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
13c40 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
13c50 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
13c60 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
13c70 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
13c80 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
13c90 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
13ca0 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
13cb0 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
13cc0 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
13cd0 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
13ce0 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
13cf0 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
13d00 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
13d10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
13d20 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
13d30 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
13d40 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
13d50 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
13d60 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
13d70 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
13d80 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
13d90 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
13da0 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
13db0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
13dc0 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
13dd0 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
13de0 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
13df0 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
13e00 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
13e10 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
13e20 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
13e30 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
13e40 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
13e50 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
13e60 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
13e70 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
13e80 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
13e90 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
13ea0 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
13eb0 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
13ec0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
13ed0 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
13ee0 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
13ef0 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
13f00 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
13f10 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
13f20 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
13f30 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
13f40 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
13f50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
13f60 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
13f70 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
13f80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13f90 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
13fa0 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
13fb0 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
13fc0 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
13fd0 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
13fe0 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
13ff0 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
14000 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
14010 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
14020 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
14030 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
14040 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14050 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
14060 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
14070 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
14080 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
14090 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
140a0 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
140b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
140c0 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
140d0 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
140e0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
140f0 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
14100 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
14110 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
14120 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
14130 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  code]..*/.SQLITE
14140 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
14150 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
14160 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
14170 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
14180 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14190 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
141a0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
141b0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
141c0 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
141d0 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
141e0 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
141f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
14200 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
14210 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
14220 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
14230 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
14240 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
14250 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
14260 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14270 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
14280 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
14290 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
142a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
142b0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
142c0 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
142d0 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
142e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
142f0 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
14300 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
14310 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
14320 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
14330 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
14340 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
14350 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
14360 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
14370 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
14380 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
14390 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
143a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
143b0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
143c0 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
143d0 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
143e0 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
143f0 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
14400 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
14410 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53  successful..*/.S
14420 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
14430 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
14440 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
14450 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
14460 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
14470 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
14480 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
14490 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
144a0 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
144b0 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
144c0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
144d0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
144e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
144f0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
14500 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
14510 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
14520 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
14530 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
14540 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
14550 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
14560 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
14570 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
14580 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
14590 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
145a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
145b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
145c0 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
145d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
145e0 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
145f0 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
14600 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
14610 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
14620 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
14630 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
14640 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
14650 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
14660 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
14670 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
14680 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
14690 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
146a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
146b0 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
146c0 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
146d0 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
146e0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
146f0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
14700 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
14710 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
14720 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
14730 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
14740 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
14750 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
14760 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
14770 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
14780 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
14790 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
147a0 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
147b0 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
147c0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
147d0 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
147e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
147f0 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
14800 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
14810 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
14820 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
14830 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
14840 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
14850 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
14860 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
14870 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
14880 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
14890 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
148a0 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
148b0 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
148c0 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
148d0 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
148e0 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
148f0 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
14900 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
14910 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
14920 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
14930 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
14940 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
14950 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
14960 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
14970 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
14980 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
14990 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
149a0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
149b0 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
149c0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
149d0 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
149e0 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
149f0 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
14a00 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
14a10 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
14a20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14a30 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
14a40 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
14a50 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
14a60 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
14a70 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
14a80 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
14a90 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
14aa0 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
14ab0 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
14ac0 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
14ad0 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
14ae0 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
14af0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
14b00 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
14b10 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
14b20 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
14b30 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
14b40 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
14b50 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
14b60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14b70 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
14b80 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
14b90 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
14ba0 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
14bb0 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
14bc0 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
14bd0 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
14be0 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
14bf0 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
14c00 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
14c10 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
14c20 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
14c30 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
14c40 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
14c50 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
14c60 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
14c70 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
14c80 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
14c90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14ca0 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
14cb0 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
14cc0 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
14cd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
14ce0 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65  r.  (For example
14cf0 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c  ,.** it might al
14d00 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69  locate any requi
14d10 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e  re mutexes or in
14d20 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61  itialize interna
14d30 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74  l data.** struct
14d40 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74  ures.  The xShut
14d50 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69  down method is i
14d60 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74  nvoked (indirect
14d70 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ly) by.** [sqlit
14d80 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61  e3_shutdown()] a
14d90 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f  nd should deallo
14da0 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63  cate any resourc
14db0 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62  es acquired.** b
14dc0 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41  y xInit.  The pA
14dd0 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69  ppData pointer i
14de0 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e  s used as the on
14df0 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  ly parameter to.
14e00 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68  ** xInit and xSh
14e10 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  utdown..**.** SQ
14e20 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b  Lite holds the [
14e30 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
14e40 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65  TIC_MASTER] mute
14e50 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65  x when it invoke
14e60 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d  s.** the xInit m
14e70 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49  ethod, so the xI
14e80 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20  nit method need 
14e90 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66  not be threadsaf
14ea0 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74  e.  The.** xShut
14eb0 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f  down method is o
14ec0 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  nly called from 
14ed0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
14ee0 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a  n()] so it does.
14ef0 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  ** not need to b
14f00 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74  e threadsafe eit
14f10 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74  her.  For all ot
14f20 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c  her methods, SQL
14f30 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65  ite.** holds the
14f40 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
14f50 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78  TATIC_MEM] mutex
14f60 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a   as long as the.
14f70 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
14f80 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e  G_MEMSTATUS] con
14f90 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14fa0 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28  n is turned on (
14fb0 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62  which.** it is b
14fc0 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73  y default) and s
14fd0 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72  o the methods ar
14fe0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
14ff0 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48  serialized..** H
15000 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49  owever, if [SQLI
15010 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
15020 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64  TUS] is disabled
15030 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72  , then the other
15040 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  .** methods must
15050 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f   be threadsafe o
15060 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69  r else make thei
15070 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e  r own arrangemen
15080 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c  ts for.** serial
15090 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  ization..**.** S
150a0 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
150b0 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20   invoke xInit() 
150c0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77  more than once w
150d0 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76  ithout an interv
150e0 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f  ening.** call to
150f0 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f   xShutdown()..*/
15100 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
15110 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
15120 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  ods sqlite3_mem_
15130 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
15140 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
15150 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a  ods {.  void *(*
15160 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20  xMalloc)(int);  
15170 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79         /* Memory
15180 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63   allocation func
15190 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28  tion */.  void (
151a0 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20  *xFree)(void*); 
151b0 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65           /* Free
151c0 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74   a prior allocat
151d0 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28  ion */.  void *(
151e0 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a  *xRealloc)(void*
151f0 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a  ,int);  /* Resiz
15200 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e an allocation 
15210 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65  */.  int (*xSize
15220 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
15230 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68      /* Return th
15240 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c  e size of an all
15250 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
15260 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74   (*xRoundup)(int
15270 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  );          /* R
15280 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20  ound up request 
15290 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  size to allocati
152a0 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74  on size */.  int
152b0 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29   (*xInit)(void*)
152c0 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49  ;           /* I
152d0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
152e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
152f0 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74  /.  void (*xShut
15300 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20  down)(void*);   
15310 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69     /* Deinitiali
15320 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
15330 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
15340 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
15350 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
15360 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74  rgument to xInit
15370 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  () and xShutdown
15380 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  () */.};../*.** 
15390 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
153a0 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
153b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
153c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
153d0 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on}.**.** These 
153e0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
153f0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
15400 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
15410 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
15420 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
15430 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
15440 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
15450 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
15460 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
15470 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
15480 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
15490 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
154a0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
154b0 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
154c0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
154d0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
154e0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
154f0 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
15500 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
15510 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
15520 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  m [sqlite3_confi
15530 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
15540 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
15550 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20  ll worked.  The 
15560 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
15570 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
15580 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
15590 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
155a0 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
155b0 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
155c0 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
155d0 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
155e0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
155f0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
15600 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
15610 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
15620 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
15630 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
15640 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
15650 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
15660 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
15670 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
15680 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
15690 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
156a0 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
156b0 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
156c0 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
156d0 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
156e0 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
156f0 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
15700 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
15710 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
15720 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
15730 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
15740 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
15750 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
15760 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
15770 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15780 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
15790 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
157a0 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
157b0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
157c0 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
157d0 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
157e0 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
157f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15800 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
15810 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
15820 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
15830 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15840 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
15850 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15860 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
15870 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15880 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20  G_MULTITHREAD]] 
15890 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
158a0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64  G_MULTITHREAD</d
158b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
158c0 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
158d0 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
158e0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
158f0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
15900 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d  ading mode] to M
15910 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e  ulti-thread.  In
15920 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
15930 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74   disables.** mut
15940 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61  exing on [databa
15950 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
15960 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
15970 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
15980 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
15990 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ion is responsib
159a0 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69  le for serializi
159b0 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20  ng access to.** 
159c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
159d0 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
159e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
159f0 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74  .  But other mut
15a00 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
15a10 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69  led so that SQLi
15a20 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20  te will be safe 
15a30 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74  to use in a mult
15a40 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e  i-threaded.** en
15a50 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e  vironment as lon
15a60 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65  g as no two thre
15a70 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75  ads attempt to u
15a80 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b  se the same.** [
15a90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15aa0 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65  ion] at the same
15ab0 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69   time.  ^If SQLi
15ac0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
15ad0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
15ae0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
15af0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
15b00 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
15b10 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
15b20 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
15b30 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d  ble to set the M
15b40 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
15b50 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
15b60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
15b70 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
15b80 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
15b90 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
15ba0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
15bb0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
15bc0 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
15bd0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
15be0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15bf0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20  IG_SERIALIZED]] 
15c00 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15c10 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74  G_SERIALIZED</dt
15c20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
15c30 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
15c40 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
15c50 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
15c60 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
15c70 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65  ding mode] to Se
15c80 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68  rialized. In oth
15c90 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f  er words, this o
15ca0 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a  ption enables.**
15cb0 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63   all mutexes inc
15cc0 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72  luding the recur
15cd0 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20  sive.** mutexes 
15ce0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
15cf0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
15d00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
15d10 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e  ] objects..** In
15d20 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63   this mode (whic
15d30 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74  h is the default
15d40 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
15d50 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
15d60 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
15d70 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69  AFE=1]) the SQLi
15d80 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
15d90 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65  itself serialize
15da0 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64   access.** to [d
15db0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15dc0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
15dd0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73  ed statements] s
15de0 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70  o that the.** ap
15df0 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65  plication is fre
15e00 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  e to use the sam
15e10 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
15e20 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a  ection] or the.*
15e30 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  * same [prepared
15e40 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64   statement] in d
15e50 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73  ifferent threads
15e60 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
15e70 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65  e..** ^If SQLite
15e80 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
15e90 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
15ea0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
15eb0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
15ec0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
15ed0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
15ee0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
15ef0 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72  e to set the Ser
15f00 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
15f10 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
15f20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
15f30 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
15f40 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
15f50 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
15f60 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
15f70 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e  G_SERIALIZED con
15f80 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15f90 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
15fa0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
15fb0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
15fc0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
15fd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15fe0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
15ff0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
16000 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
16010 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
16020 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
16030 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
16040 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
16050 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
16060 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
16070 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
16080 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16090 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
160a0 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
160b0 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
160c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
160d0 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
160e0 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
160f0 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
16100 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
16110 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
16120 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
16130 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
16140 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
16150 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
16160 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
16170 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
16180 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16190 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
161a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
161b0 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
161c0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
161d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
161e0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
161f0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16200 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
16210 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
16220 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
16230 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
16240 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
16250 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
16260 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
16270 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
16280 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
16290 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
162a0 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
162b0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
162c0 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
162d0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
162e0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
162f0 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
16300 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
16310 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
16320 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
16330 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
16340 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
16350 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
16360 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16370 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64  G_MEMSTATUS]] <d
16380 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16390 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a  MEMSTATUS</dt>.*
163a0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
163b0 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
163c0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
163d0 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
163e0 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c  ed as a .** bool
163f0 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
16400 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
16410 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
16420 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16430 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63  on .** statistic
16440 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
16450 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
16460 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
16470 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c  led, the .** fol
16480 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
16490 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
164a0 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
164b0 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
164c0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
164d0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
164e0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
164f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
16500 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
16510 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
16520 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
16530 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
16540 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tatus()].**   </
16550 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
16560 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
16570 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
16580 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
16590 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
165a0 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
165b0 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
165c0 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
165d0 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
165e0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
165f0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
16600 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
16610 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
16620 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16630 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
16640 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
16650 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
16660 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
16670 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
16680 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
16690 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
166a0 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72  n use for.** scr
166b0 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68  atch memory.  Th
166c0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
166d0 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e  guments:  A poin
166e0 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
166f0 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
16700 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
16710 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
16720 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
16730 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
16740 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
16750 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
16760 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
16770 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
16780 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
16790 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65  ations (N).  The
167a0 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20   sz.** argument 
167b0 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70  must be a multip
167c0 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65  le of 16..** The
167d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
167e0 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65  must be a pointe
167f0 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
16800 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a  ligned buffer.**
16810 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
16820 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
16830 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
16840 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74  ll use no more t
16850 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20  han two scratch 
16860 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65  buffers per thre
16870 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f  ad.  So.** N sho
16880 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77  uld be set to tw
16890 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64  ice the expected
168a0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
168b0 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e  of threads..** ^
168c0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
168d0 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61  r require a scra
168e0 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
168f0 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a  is more than 6.*
16900 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61  * times the data
16910 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20  base page size. 
16920 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
16930 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
16940 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
16950 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
16960 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
16970 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
16980 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
16990 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
169a0 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
169b0 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
169c0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
169d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
169e0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
169f0 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
16a00 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
16a10 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
16a20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
16a30 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
16a40 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
16a50 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
16a60 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74  e for.** the dat
16a70 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
16a80 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
16a90 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
16aa0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
16ab0 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
16ac0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
16ad0 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70  be used if an ap
16ae0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
16af0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
16b00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
16b10 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
16b20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16b30 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a  PCACHE2 option..
16b40 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
16b50 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
16b60 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70  this option: A p
16b70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65  ointer to 8-byte
16b80 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f   aligned.** memo
16b90 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
16ba0 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
16bb0 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
16bc0 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
16bd0 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
16be0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
16bf0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
16c00 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
16c10 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
16c20 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
16c30 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29  n 512 and 32768)
16c40 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65   plus a little e
16c50 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a  xtra for each.**
16c60 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e   page header.  ^
16c70 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20  The page header 
16c80 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30  size is 20 to 40
16c90 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67   bytes depending
16ca0 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20   on.** the host 
16cb0 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e  architecture.  ^
16cc0 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
16cd0 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
16ce0 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
16cf0 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69   to make sz a li
16d00 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20  ttle too large. 
16d10 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
16d20 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
16d30 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
16d40 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
16d50 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
16d60 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
16d70 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d  e will use the m
16d80 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62  emory provided b
16d90 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
16da0 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20  ment to satisfy 
16db0 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65  its.** memory ne
16dc0 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73  eds for the firs
16dd0 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69  t N pages that i
16de0 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e  t adds to cache.
16df0 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c    ^If additional
16e00 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
16e10 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
16e20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
16e30 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
16e40 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
16e50 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
16e60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16e70 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
16e80 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
16e90 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  ce..** The point
16ea0 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
16eb0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a  argument must.**
16ec0 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
16ed0 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
16ee0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
16ef0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
16f00 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e  te.** will be un
16f10 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
16f20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16f30 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
16f40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
16f50 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
16f60 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
16f70 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
16f80 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
16f90 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
16fa0 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20  e.** for all of 
16fb0 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
16fc0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
16fd0 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  eds beyond those
16fe0 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
16ff0 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
17000 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20  IG_SCRATCH] and 
17010 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
17020 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
17030 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
17040 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79  guments: An 8-by
17050 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
17060 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
17070 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
17080 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
17090 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
170a0 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
170b0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
170c0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
170d0 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
170e0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
170f0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
17100 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
17110 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
17120 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
17130 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
17140 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
17150 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
17160 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
17170 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
17180 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
17190 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
171a0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
171b0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20  is not NULL and 
171c0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
171d0 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
171e0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  r.** [SQLITE_ENA
171f0 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65  BLE_MEMSYS5] are
17200 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74   defined, then t
17210 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
17220 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
17230 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
17240 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
17250 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
17260 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
17270 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
17280 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
17290 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
172a0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
172b0 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
172c0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
172d0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
172e0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
172f0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
17300 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
17310 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
17320 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
17330 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
17340 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
17350 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
17360 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
17370 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
17380 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
17390 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
173a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
173b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
173c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
173d0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
173e0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
173f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
17400 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
17410 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
17420 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
17430 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
17440 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
17450 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
17460 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
17470 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
17480 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75   place.** the mu
17490 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
174a0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
174b0 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
174c0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
174d0 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  * content of the
174e0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
174f0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
17500 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
17510 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
17520 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
17530 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
17540 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
17550 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
17560 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
17570 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
17580 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
17590 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
175a0 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
175b0 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
175c0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
175d0 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
175e0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
175f0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
17600 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
17610 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
17620 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17630 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
17640 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
17650 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
17660 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
17670 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
17680 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
17690 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
176a0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
176b0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
176c0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
176d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
176e0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
176f0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
17700 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
17710 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
17720 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
17730 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
17740 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
17750 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
17760 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
17770 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
17780 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
17790 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
177a0 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
177b0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
177c0 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
177d0 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
177e0 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
177f0 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
17800 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
17810 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
17820 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
17830 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
17840 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
17850 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
17860 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
17870 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
17880 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
17890 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
178a0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
178b0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
178c0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
178d0 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
178e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
178f0 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
17900 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
17910 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
17920 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
17930 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
17940 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
17950 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
17960 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74  _LOOKASIDE]] <dt
17970 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
17980 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
17990 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
179a0 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
179b0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
179c0 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75  ermine the defau
179d0 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt.** memory all
179e0 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  ocation for the 
179f0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
17a00 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61   allocator on ea
17a10 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
17a20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
17a30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17a40 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
17a50 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
17a60 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
17a70 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
17a80 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
17a90 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
17aa0 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
17ab0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
17ac0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73   ^(This option s
17ad0 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65  ets the.** <i>de
17ae0 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
17af0 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
17b00 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
17b10 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72  OOKASIDE].** ver
17b20 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  b to [sqlite3_db
17b30 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
17b40 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
17b50 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
17b60 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
17b70 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
17b80 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
17b90 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
17ba0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
17bb0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
17bc0 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
17bd0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
17be0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
17bf0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
17c00 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
17c10 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c  er to.** an [sql
17c20 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
17c30 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54  ods2] object.  T
17c40 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
17c50 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  fies the interfa
17c60 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f  ce.** to a custo
17c70 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
17c80 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20  lementation.)^  
17c90 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
17ca0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
17cb0 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69  bject and uses i
17cc0 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65  t for page cache
17cd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
17ce0 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ons.</dd>.**.** 
17cf0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17d00 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
17d10 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
17d20 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
17d30 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
17d40 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
17d50 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
17d60 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
17d70 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
17d80 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
17d90 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  2] object.  SQLi
17da0 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65  te copies of the
17db0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65   current.** page
17dc0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
17dd0 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
17de0 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
17df0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
17e00 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e  ONFIG_LOG]] <dt>
17e10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
17e20 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  G</dt>.** <dd> ^
17e30 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
17e40 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
17e50 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
17e60 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
17e70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
17e80 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
17e90 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
17ea0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
17eb0 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
17ec0 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
17ed0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
17ee0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
17ef0 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
17f00 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
17f10 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
17f20 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
17f30 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
17f40 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
17f50 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
17f60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
17f70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
17f80 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
17f90 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
17fa0 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
17fb0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
17fc0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
17fd0 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
17fe0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
17ff0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
18000 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
18010 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
18020 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
18030 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
18040 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
18050 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
18060 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
18070 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
18080 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
18090 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
180a0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
180b0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
180c0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
180d0 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
180e0 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
180f0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
18100 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
18110 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
18120 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
18130 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
18140 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
18150 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
18160 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
18170 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
18180 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
18190 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
181a0 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
181b0 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
181c0 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
181d0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
181e0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
181f0 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
18200 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
18210 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
18220 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
18230 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
18240 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
18250 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
18260 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
18270 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
18280 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
18290 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
182a0 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68  G_URI.** <dd> Th
182b0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
182c0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
182d0 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49  t of type int. I
182e0 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
182f0 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  .** URI handling
18300 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
18310 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
18320 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20  ameter is zero, 
18330 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
18340 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79  g.** is globally
18350 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52   disabled. If UR
18360 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
18370 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20  obally enabled, 
18380 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a  all filenames.**
18390 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
183a0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
183b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
183c0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
183d0 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
183e0 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
183f0 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
18400 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
18410 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
18420 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
18430 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
18440 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
18450 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
18460 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
18470 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
18480 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73  opened. If it is
18490 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
184a0 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  ed, filenames ar
184b0 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70  e.** only interp
184c0 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66  reted as URIs if
184d0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
184e0 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74  _URI flag is set
184f0 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74   when the.** dat
18500 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18510 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64   is opened. By d
18520 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64  efault, URI hand
18530 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
18540 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68  .** disabled. Th
18550 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
18560 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62  may be changed b
18570 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68  y compiling with
18580 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
18590 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20  USE_URI] symbol 
185a0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b  defined..**.** [
185b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
185c0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
185d0 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
185e0 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
185f0 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
18600 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  d> This option t
18610 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
18620 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77  teger argument w
18630 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
18640 74 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c  ted as.** a bool
18650 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
18660 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
18670 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
18680 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
18690 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20  r.** full table 
186a0 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
186b0 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54  ry optimizer.  T
186c0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
186d0 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
186e0 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
186f0 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
18700 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
18710 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
18720 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
18730 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
18740 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
18750 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
18760 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
18770 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
18780 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
18790 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
187a0 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
187b0 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
187c0 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
187d0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
187e0 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
187f0 2a 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68  * malfunction wh
18800 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  en the optimizat
18810 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20  ion is enabled. 
18820 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61   Providing the a
18830 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73  bility to.** dis
18840 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a  able the optimiz
18850 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65  ation allows the
18860 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70   older, buggy ap
18870 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74  plication code t
18880 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75  o work.** withou
18890 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69  t change even wi
188a0 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  th newer version
188b0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
188c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
188d0 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51  IG_PCACHE]] [[SQ
188e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
188f0 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  CACHE]].** <dt>S
18900 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
18910 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43  CHE and SQLITE_C
18920 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a  ONFIG_GETPCACHE.
18930 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70  ** <dd> These op
18940 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65  tions are obsole
18950 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  te and should no
18960 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77  t be used by new
18970 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61   code..** They a
18980 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
18990 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
189a0 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20  ibility but are 
189b0 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c  now no-ops..** <
189c0 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dl>.**.** [[SQL
189d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
189e0 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  G]].** <dt>SQLIT
189f0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a  E_CONFIG_SQLLOG.
18a00 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
18a10 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
18a20 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69  able if sqlite i
18a30 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
18a40 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e  the.** SQLITE_EN
18a50 41 42 4c 45 5f 53 51 4c 4c 4f 47 20 70 72 65 2d  ABLE_SQLLOG pre-
18a60 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
18a70 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72  defined. The fir
18a80 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  st argument shou
18a90 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74  ld.** be a point
18aa0 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  er to a function
18ab0 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29   of type void(*)
18ac0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
18ad0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
18ae0 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
18af0 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79   should be of ty
18b00 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20  pe (void*). The 
18b10 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
18b20 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61  ked by the libra
18b30 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73  ry.** in three s
18b40 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74  eparate circumst
18b50 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65  ances, identifie
18b60 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70  d by the value p
18b70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20  assed as the.** 
18b80 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
18b90 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  . If the fourth 
18ba0 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20  parameter is 0, 
18bb0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
18bc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
18bd0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
18be0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61  cond argument ha
18bf0 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e  s just been open
18c00 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72  ed. The third ar
18c10 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73  gument.** points
18c20 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e   to a buffer con
18c30 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65  taining the name
18c40 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74   of the main dat
18c50 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74  abase file. If t
18c60 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
18c70 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65  ameter is 1, the
18c80 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
18c90 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69  ent that the thi
18ca0 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
18cb0 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75  points to has ju
18cc0 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64  st been executed
18cd0 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75  . Or, if the fou
18ce0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
18cf0 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20   2, then.** the 
18d00 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67  connection being
18d10 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
18d20 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18d30 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e  is being closed.
18d40 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   The.** third pa
18d50 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65  rameter is passe
18d60 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63  d NULL In this c
18d70 61 73 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  ase..** </dl>.*/
18d80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18d90 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
18da0 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
18db0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18dc0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
18dd0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
18de0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18df0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
18e00 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
18e10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18e20 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
18e30 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
18e40 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
18e50 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
18e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
18e70 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
18e80 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
18e90 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
18ea0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
18eb0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
18ec0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
18ed0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
18ee0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18ef0 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
18f00 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
18f10 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
18f20 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18f30 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
18f40 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
18f50 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
18f60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18f70 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
18f80 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
18f90 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
18fa0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
18fb0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
18fc0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
18fd0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
18fe0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18ff0 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
19000 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
19010 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
19020 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
19030 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
19040 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
19050 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
19060 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
19070 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
19080 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
19090 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
190a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
190b0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
190c0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
190d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
190e0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
190f0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
19100 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
19110 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
19120 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
19130 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
19140 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
19150 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
19160 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
19170 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
19180 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
19190 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
191a0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
191b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
191c0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
191d0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
191e0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
191f0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
19200 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
19210 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
19220 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
19230 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
19240 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
19250 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
19260 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  void* */../*.** 
19270 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
19280 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
19290 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
192a0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
192b0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
192c0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
192d0 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
192e0 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
192f0 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
19300 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
19310 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
19320 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
19330 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
19340 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
19350 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
19360 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
19370 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
19380 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
19390 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
193a0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
193b0 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
193c0 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
193d0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
193e0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
193f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
19400 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
19410 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
19420 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
19430 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
19440 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
19450 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
19460 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
19470 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
19480 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
19490 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
194a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
194b0 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
194c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
194d0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
194e0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
194f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
19500 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
19510 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
19520 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
19530 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
19540 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
19550 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
19560 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
19570 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
19580 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
19590 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
195a0 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
195b0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
195c0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
195d0 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
195e0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66   to a memory buf
195f0 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
19600 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
19610 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
19620 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
19630 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
19640 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
19650 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
19660 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
19670 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
19680 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
19690 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
196a0 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
196b0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
196c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
196d0 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
196e0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
196f0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
19700 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
19710 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
19720 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
19730 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
19740 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
19750 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
19760 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
19770 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
19780 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
19790 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
197a0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
197b0 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
197c0 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
197d0 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
197e0 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
197f0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
19800 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
19810 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
19820 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
19830 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
19840 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
19850 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
19860 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74  ext smaller mult
19870 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68  iple of 8.  ^(Th
19880 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
19890 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  ry.** configurat
198a0 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61  ion for a databa
198b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61  se connection ca
198c0 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65  n only be change
198d0 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63  d when that.** c
198e0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74  onnection is not
198f0 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
19900 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
19910 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77  y, or in other w
19920 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65  ords.** when the
19930 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22   "current value"
19940 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
19950 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74  [sqlite3_db_stat
19960 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f  us](D,[SQLITE_CO
19970 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
19980 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  ...) is zero..**
19990 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
199a0 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
199b0 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66  side memory conf
199c0 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c  iguration when l
199d0 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f  ookaside.** memo
199e0 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61  ry is in use lea
199f0 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72  ves the configur
19a00 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20  ation unchanged 
19a10 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  and returns .** 
19a20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e  [SQLITE_BUSY].)^
19a30 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
19a40 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19a50 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e  ENABLE_FKEY</dt>
19a60 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
19a70 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
19a80 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
19a90 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65  le the enforceme
19aa0 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67  nt of.** [foreig
19ab0 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74  n key constraint
19ac0 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c  s].  There shoul
19ad0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
19ae0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
19af0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
19b00 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
19b10 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
19b20 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f   disable FK enfo
19b30 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69  rcement,.** posi
19b40 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46  tive to enable F
19b50 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72  K enforcement or
19b60 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
19b70 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  ve FK enforcemen
19b80 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20  t.** unchanged. 
19b90 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
19ba0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
19bb0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
19bc0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
19bd0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
19be0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
19bf0 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d  ther FK enforcem
19c00 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e  ent is off or on
19c10 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
19c20 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
19c30 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
19c40 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
19c50 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
19c60 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e  h case the FK en
19c70 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e  forcement settin
19c80 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
19c90 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
19ca0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
19cb0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
19cc0 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  RIGGER</dt>.** <
19cd0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
19ce0 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
19cf0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43  le or disable [C
19d00 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
19d10 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68  triggers]..** Th
19d20 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
19d30 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
19d40 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
19d50 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
19d60 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
19d70 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
19d80 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70  e triggers,.** p
19d90 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
19da0 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65  e triggers or ne
19db0 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
19dc0 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68  the setting unch
19dd0 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
19de0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
19df0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
19e00 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
19e10 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
19e20 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
19e30 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72  icate whether tr
19e40 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62  iggers are disab
19e50 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
19e60 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
19e70 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
19e80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
19e90 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
19ea0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
19eb0 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72  case the trigger
19ec0 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
19ed0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
19ee0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
19ef0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
19f00 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
19f10 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31  ASIDE       1001
19f20 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
19f30 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
19f40 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
19f50 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30  ABLE_FKEY     10
19f60 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  02  /* int int* 
19f70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19f80 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19f90 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20  E_TRIGGER  1003 
19fa0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
19fb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19fc0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
19fd0 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
19fe0 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ult Codes.**.** 
19ff0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
1a000 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
1a010 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
1a020 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
1a030 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
1a040 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
1a050 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
1a060 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64  e. ^The extended
1a070 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
1a080 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
1a090 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
1a0a0 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
1a0b0 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ility..*/.SQLITE
1a0c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1a0d0 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
1a0e0 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
1a0f0 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
1a100 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
1a110 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
1a120 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
1a130 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
1a140 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
1a150 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
1a160 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
1a170 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
1a180 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
1a190 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
1a1a0 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
1a1b0 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
1a1c0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
1a1d0 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
1a1e0 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
1a1f0 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
1a200 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
1a210 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
1a220 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
1a230 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
1a240 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
1a250 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
1a260 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
1a270 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
1a280 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
1a290 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
1a2a0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1a2b0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1a2c0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d  [rowid] of the m
1a2d0 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75  ost recent.** su
1a2e0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
1a2f0 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  ] into the datab
1a300 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61  ase from the [da
1a310 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a320 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
1a330 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41  st argument.  ^A
1a340 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
1a350 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20  ion 3.7.7, this 
1a360 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f  routines.** reco
1a370 72 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  rds the last ins
1a380 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74  ert rowid of bot
1a390 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65  h ordinary table
1a3a0 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74  s and [virtual t
1a3b0 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e  ables]..** ^If n
1a3c0 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
1a3d0 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65  SERT]s.** have e
1a3e0 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
1a3f0 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f  that database co
1a400 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69  nnection, zero i
1a410 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1a420 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
1a430 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
1a440 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69   a trigger or wi
1a450 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20  thin a [virtual 
1a460 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64  table].** method
1a470 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  , then this rout
1a480 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ine will return 
1a490 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
1a4a0 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
1a4b0 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ow as long as th
1a4c0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
1a4d0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
1a4e0 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  d is running..**
1a4f0 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
1a500 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
1a510 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e   table method en
1a520 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
1a530 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
1a540 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
1a550 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
1a560 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
1a570 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a  gger or virtual.
1a580 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  ** table method 
1a590 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  began.)^.**.** ^
1a5a0 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74  An [INSERT] that
1a5b0 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
1a5c0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
1a5d0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
1a5e0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
1a5f0 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f  ERT] and does no
1a600 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
1a610 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
1a620 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
1a630 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52   ^Thus INSERT OR
1a640 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52   FAIL, INSERT OR
1a650 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20   IGNORE, INSERT 
1a660 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20  OR ROLLBACK,.** 
1a670 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42  and INSERT OR AB
1a680 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e  ORT make no chan
1a690 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72  ges to the retur
1a6a0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a  n value of this.
1a6b0 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20  ** routine when 
1a6c0 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20  their insertion 
1a6d0 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49  fails.  ^(When I
1a6e0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
1a6f0 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
1a700 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
1a710 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
1a720 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
1a730 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
1a740 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
1a750 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
1a760 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
1a770 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
1a780 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
1a790 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
1a7a0 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
1a7b0 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
1a7c0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
1a7d0 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  terface.)^.**.**
1a7e0 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
1a7f0 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
1a800 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
1a810 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
1a820 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
1a830 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
1a840 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
1a850 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
1a860 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
1a870 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53   accessible to S
1a880 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69  QL statements vi
1a890 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69  a the.** [last_i
1a8a0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
1a8b0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
1a8c0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1a8d0 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
1a8e0 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
1a8f0 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  on the same.** d
1a900 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a910 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
1a920 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
1a930 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75  t_rowid()].** fu
1a940 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
1a950 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
1a960 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
1a970 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74  rt [rowid],.** t
1a980 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
1a990 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1a9a0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1a9b0 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e  owid()] is.** un
1a9c0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1a9d0 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20  might not equal 
1a9e0 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f  either the old o
1a9f0 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73  r the new.** las
1aa00 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
1aa10 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1aa20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1aa30 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
1aa40 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
1aa50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1aa60 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
1aa70 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
1aa80 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
1aa90 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1aaa0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1aab0 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
1aac0 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
1aad0 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
1aae0 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
1aaf0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
1ab00 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
1ab10 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
1ab20 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1ab30 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
1ab40 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  d by the first p
1ab50 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f  arameter..** ^(O
1ab60 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74  nly changes that
1ab70 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
1ab80 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b  ecified by the [
1ab90 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
1aba0 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45  ],.** or [DELETE
1abb0 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20  ] statement are 
1abc0 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69  counted.  Auxili
1abd0 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
1abe0 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72  ed by.** trigger
1abf0 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65  s or [foreign ke
1ac00 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e  y actions] are n
1ac10 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73  ot counted.)^ Us
1ac20 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
1ac30 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1ac40 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66  )] function to f
1ac50 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  ind the total nu
1ac60 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a  mber of changes.
1ac70 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  ** including cha
1ac80 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
1ac90 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65  riggers and fore
1aca0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e  ign key actions.
1acb0 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20  .**.** ^Changes 
1acc0 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
1acd0 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20  re simulated by 
1ace0 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
1acf0 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e  rigger].** are n
1ad00 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c  ot counted.  Onl
1ad10 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61  y real table cha
1ad20 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
1ad30 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77  ..**.** ^(A "row
1ad40 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68   change" is a ch
1ad50 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65  ange to a single
1ad60 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65   row of a single
1ad70 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64   table.** caused
1ad80 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44   by an INSERT, D
1ad90 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45  ELETE, or UPDATE
1ada0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77   statement.  Row
1adb0 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68  s that.** are ch
1adc0 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66  anged as side ef
1add0 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43  fects of [REPLAC
1ade0 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
1adf0 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c  solution,.** rol
1ae00 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f  lback, ABORT pro
1ae10 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54  cessing, [DROP T
1ae20 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79  ABLE], or by any
1ae30 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e   other.** mechan
1ae40 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  isms do not coun
1ae50 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20  t as direct row 
1ae60 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a  changes.)^.**.**
1ae70 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74   A "trigger cont
1ae80 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20  ext" is a scope 
1ae90 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61  of execution tha
1aea0 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20  t begins and.** 
1aeb0 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63  ends with the sc
1aec0 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54  ript of a [CREAT
1aed0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
1aee0 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53  ger]. .** Most S
1aef0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
1af00 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f  e.** evaluated o
1af10 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72  utside of any tr
1af20 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20  igger.  This is 
1af30 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a  the "top level".
1af40 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
1af50 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65  xt.  If a trigge
1af60 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65  r fires from the
1af70 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a   top level, a.**
1af80 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
1af90 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20  text is entered 
1afa0 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e  for the duration
1afb0 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20   of that one.** 
1afc0 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69  trigger.  Subtri
1afd0 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62  ggers create sub
1afe0 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65  contexts for the
1aff0 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  ir duration..**.
1b000 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  ** ^Calling [sql
1b010 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20  ite3_exec()] or 
1b020 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1b030 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65   recursively doe
1b040 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20  s.** not create 
1b050 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  a new trigger co
1b060 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntext..**.** ^Th
1b070 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1b080 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1b090 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  f direct row cha
1b0a0 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d  nges in the.** m
1b0b0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
1b0c0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
1b0d0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
1b0e0 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a  ithin the same.*
1b0f0 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
1b100 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20  t..**.** ^Thus, 
1b110 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d  when called from
1b120 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
1b130 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
1b140 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  turns the.** num
1b150 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
1b160 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
1b170 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
1b180 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
1b190 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65  hat also occurre
1b1a0 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76  d at the top lev
1b1b0 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68  el.  ^(Within th
1b1c0 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
1b1d0 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ger,.** the sqli
1b1e0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
1b1f0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63  terface can be c
1b200 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
1b210 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
1b220 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
1b230 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
1b240 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
1b250 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
1b260 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
1b270 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
1b280 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
1b290 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
1b2a0 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
1b2b0 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
1b2c0 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  de changes.** ca
1b2d0 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
1b2e0 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20  ers since those 
1b2f0 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
1b300 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ontext.)^.**.** 
1b310 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
1b320 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1b330 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1b340 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
1b350 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
1b360 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65   and the [change
1b370 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1b380 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
1b390 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
1b3a0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
1b3b0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
1b3c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
1b3d0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
1b3e0 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
1b3f0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
1b400 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
1b410 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
1b420 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
1b430 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
1b440 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  I int sqlite3_ch
1b450 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1b460 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b470 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
1b480 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
1b490 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1b4a0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1b4b0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63   number of row c
1b4c0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
1b4d0 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55   [INSERT],.** [U
1b4e0 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
1b4f0 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  E] statements si
1b500 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  nce the [databas
1b510 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61  e connection] wa
1b520 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54  s opened..** ^(T
1b530 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65  he count returne
1b540 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74  d by sqlite3_tot
1b550 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63  al_changes() inc
1b560 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65  ludes all change
1b570 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43  s.** from all [C
1b580 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
1b590 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74  trigger] context
1b5a0 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61  s and changes ma
1b5b0 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67  de by.** [foreig
1b5c0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20  n key actions]. 
1b5d0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20  However,.** the 
1b5e0 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
1b5f0 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
1b600 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1b610 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
1b620 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f  raints,.** do ro
1b630 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54  llbacks or ABORT
1b640 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20   processing, or 
1b650 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f  [DROP TABLE] pro
1b660 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a  cessing.  The.**
1b670 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
1b680 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20  include rows of 
1b690 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20  views that fire 
1b6a0 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
1b6b0 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75  rigger],.** thou
1b6c0 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41  gh if the INSTEA
1b6d0 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b  D OF trigger mak
1b6e0 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74  es changes of it
1b6f0 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61  s own, those cha
1b700 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75  nges .** are cou
1b710 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  nted.)^.** ^The 
1b720 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1b730 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
1b740 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e   counts the chan
1b750 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a  ges as soon as.*
1b760 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  * the statement 
1b770 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20  that makes them 
1b780 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68  is completed (wh
1b790 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
1b7a0 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61   handle.** is pa
1b7b0 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
1b7c0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
1b7d0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1b7e0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
1b7f0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
1b800 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
1b810 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
1b820 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
1b830 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f  ma], and the [to
1b840 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51  tal_changes() SQ
1b850 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
1b860 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1b870 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
1b880 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
1b890 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b8a0 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
1b8b0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1b8c0 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
1b8d0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
1b8e0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
1b8f0 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
1b900 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
1b910 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
1b920 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  I int sqlite3_to
1b930 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
1b940 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1b950 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
1b960 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
1b970 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68   Query.**.** ^Th
1b980 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
1b990 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
1b9a0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
1b9b0 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
1b9c0 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
1b9d0 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
1b9e0 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
1b9f0 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
1ba00 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
1ba10 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
1ba20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
1ba30 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
1ba40 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
1ba50 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
1ba60 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
1ba70 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
1ba80 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
1ba90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
1baa0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
1bab0 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
1bac0 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
1bad0 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
1bae0 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
1baf0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
1bb00 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
1bb10 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
1bb20 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
1bb30 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
1bb40 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
1bb50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
1bb60 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
1bb70 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
1bb80 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
1bb90 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
1bba0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
1bbb0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
1bbc0 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
1bbd0 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
1bbe0 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
1bbf0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
1bc00 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
1bc10 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
1bc20 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
1bc30 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
1bc40 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
1bc50 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
1bc60 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
1bc70 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
1bc80 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
1bc90 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
1bca0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
1bcb0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
1bcc0 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
1bcd0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
1bce0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
1bcf0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
1bd00 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
1bd10 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
1bd20 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
1bd30 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
1bd40 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
1bd50 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
1bd60 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
1bd70 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1bd80 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
1bd90 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
1bda0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1bdb0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
1bdc0 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
1bdd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1bde0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
1bdf0 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
1be00 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1be10 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1be20 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1be30 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
1be40 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
1be50 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
1be60 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
1be70 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
1be80 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
1be90 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
1bea0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
1beb0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1bec0 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
1bed0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1bee0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1bef0 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
1bf00 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
1bf10 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
1bf20 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
1bf30 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
1bf40 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
1bf50 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1bf60 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
1bf70 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
1bf80 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
1bf90 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
1bfa0 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
1bfb0 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
1bfc0 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
1bfd0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1bfe0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1bff0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1c000 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
1c010 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
1c020 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1c030 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
1c040 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
1c050 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
1c060 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
1c070 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
1c080 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51  ly happen..*/.SQ
1c090 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
1c0a0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1c0b0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1c0c0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
1c0d0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
1c0e0 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
1c0f0 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
1c100 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
1c110 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
1c120 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
1c130 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
1c140 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
1c150 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
1c160 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
1c170 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1c180 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
1c190 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
1c1a0 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
1c1b0 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
1c1c0 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
1c1d0 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
1c1e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1c1f0 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
1c200 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
1c210 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
1c220 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1c230 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
1c240 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
1c250 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
1c260 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
1c270 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
1c280 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
1c290 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
1c2a0 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
1c2b0 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
1c2c0 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
1c2d0 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
1c2e0 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
1c2f0 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
1c300 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
1c310 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
1c320 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
1c330 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
1c340 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
1c350 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
1c360 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
1c370 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
1c380 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
1c390 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
1c3a0 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
1c3b0 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
1c3c0 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
1c3d0 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
1c3e0 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
1c3f0 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
1c400 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1c410 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
1c420 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
1c430 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
1c440 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1c450 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
1c460 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
1c470 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
1c480 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
1c490 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
1c4a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
1c4b0 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
1c4c0 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
1c4d0 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
1c4e0 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
1c4f0 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
1c500 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
1c510 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
1c520 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
1c530 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
1c540 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
1c550 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
1c560 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1c570 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1c580 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
1c590 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1c5a0 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
1c5b0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
1c5c0 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
1c5d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1c5e0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
1c5f0 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
1c600 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
1c610 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1c620 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
1c630 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
1c640 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
1c650 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1c660 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
1c670 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1c680 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
1c690 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
1c6a0 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1c6b0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1c6c0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1c6d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1c6e0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
1c6f0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1c700 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  er..*/.SQLITE_AP
1c710 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
1c720 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
1c730 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f  r *sql);.SQLITE_
1c740 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1c750 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
1c760 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
1c770 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1c780 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
1c790 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
1c7a0 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
1c7b0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1c7c0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
1c7d0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
1c7e0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
1c7f0 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  d whenever.** an
1c800 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
1c810 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
1c820 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61  ase table that a
1c830 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
1c840 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
1c850 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  locked..**.** ^I
1c860 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
1c870 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
1c880 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
1c890 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
1c8a0 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20  _BLOCKED].** is 
1c8b0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
1c8c0 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
1c8d0 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
1c8e0 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
1c8f0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
1c900 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
1c910 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
1c920 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
1c930 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
1c940 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1c950 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1c960 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1c970 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
1c980 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
1c990 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
1c9a0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
1c9b0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1c9c0 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
1c9d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
1c9e0 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
1c9f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1ca00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
1ca10 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
1ca20 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
1ca30 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
1ca40 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
1ca50 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
1ca60 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
1ca70 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
1ca80 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
1ca90 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
1caa0 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
1cab0 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
1cac0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
1cad0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
1cae0 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64  KED] is returned
1caf0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
1cb00 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1cb10 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
1cb20 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
1cb30 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
1cb40 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
1cb50 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
1cb60 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
1cb70 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
1cb80 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
1cb90 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
1cba0 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
1cbb0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
1cbc0 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
1cbd0 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
1cbe0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
1cbf0 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
1cc00 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
1cc10 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
1cc20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
1cc30 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
1cc40 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
1cc50 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1cc60 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
1cc70 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
1cc80 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
1cc90 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1cca0 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
1ccb0 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
1ccc0 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
1ccd0 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
1cce0 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
1ccf0 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
1cd00 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
1cd10 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
1cd20 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
1cd30 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
1cd40 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
1cd50 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
1cd60 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
1cd70 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
1cd80 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
1cd90 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
1cda0 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
1cdb0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1cdc0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
1cdd0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
1cde0 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
1cdf0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1ce00 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
1ce10 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
1ce20 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
1ce30 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
1ce40 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
1ce50 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
1ce60 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
1ce70 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
1ce80 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
1ce90 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
1cea0 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
1ceb0 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
1cec0 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
1ced0 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
1cee0 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
1cef0 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
1cf00 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1cf10 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
1cf20 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1cf30 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
1cf40 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
1cf50 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  The [SQLITE_BUSY
1cf60 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65  ] error is conve
1cf70 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f  rted to [SQLITE_
1cf80 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
1cf90 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
1cfa0 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
1cfb0 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61  f a large transa
1cfc0 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20  ction where all 
1cfd0 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77  the.** changes w
1cfe0 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f  ill not fit into
1cff0 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63   the in-memory c
1d000 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69  ache.  SQLite wi
1d010 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f  ll.** already ho
1d020 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f  ld a RESERVED lo
1d030 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ck on the databa
1d040 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20  se file, but it 
1d050 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d  needs.** to prom
1d060 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f  ote this lock to
1d070 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68   EXCLUSIVE so th
1d080 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20  at it can spill 
1d090 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69  cache.** pages i
1d0a0 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
1d0b0 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61   file without ha
1d0c0 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74  rm to concurrent
1d0d0 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49  .** readers.  ^I
1d0e0 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
1d0f0 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f  o promote the lo
1d100 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d  ck, then the in-
1d110 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20  memory.** cache 
1d120 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20  will be left in 
1d130 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20  an inconsistent 
1d140 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65  state and so the
1d150 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
1d160 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20  s promoted from 
1d170 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62  the relatively b
1d180 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55  enign [SQLITE_BU
1d190 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f  SY] to.** the mo
1d1a0 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54  re severe [SQLIT
1d1b0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
1d1c0 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63  .  ^This error c
1d1d0 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
1d1e0 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
1d1f0 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
1d200 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53   the changes.  S
1d210 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  ee the.** <a hre
1d220 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69  f="/cvstrac/wiki
1d230 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ?p=CorruptionFol
1d240 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22  lowingBusyError"
1d250 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46  >.** CorruptionF
1d260 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
1d270 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20  r</a> wiki page 
1d280 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e  for a discussion
1d290 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20   of why.** this 
1d2a0 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a  is important..**
1d2b0 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1d2c0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1d2d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
1d2e0 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
1d2f0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1d300 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
1d310 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
1d320 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
1d330 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
1d340 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
1d350 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
1d360 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1d370 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c  imeout()].** wil
1d380 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c  l also set or cl
1d390 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e  ear the busy han
1d3a0 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dler..**.** The 
1d3b0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68  busy callback sh
1d3c0 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e  ould not take an
1d3d0 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20  y actions which 
1d3e0 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61  modify the.** da
1d3f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d400 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1d410 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1d420 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
1d430 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
1d440 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
1d450 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
1d460 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
1d470 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
1d480 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d490 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
1d4a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1d4b0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1d4c0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51  y handler..*/.SQ
1d4d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1d4e0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1d4f0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
1d500 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
1d510 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1d520 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
1d530 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a  sy Timeout.**.**
1d540 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
1d550 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
1d560 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
1d570 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
1d580 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
1d590 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
1d5a0 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
1d5b0 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
1d5c0 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
1d5d0 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
1d5e0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
1d5f0 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
1d600 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1d610 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
1d620 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
1d630 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
1d640 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1d650 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
1d660 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
1d670 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
1d680 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
1d690 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
1d6a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
1d6b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
1d6c0 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a  R_BLOCKED]..**.*
1d6d0 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
1d6e0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
1d6f0 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
1d700 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
1d710 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
1d720 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
1d730 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
1d740 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1d750 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1d760 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
1d770 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1d780 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
1d790 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  y any given mome
1d7a0 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
1d7b0 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
1d7c0 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
1d7d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1d7e0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
1d7f0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
1d800 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
1d810 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
1d820 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
1d830 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ed.)^.*/.SQLITE_
1d840 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1d850 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
1d860 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
1d870 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d880 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
1d890 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
1d8a0 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20  g Queries.**.** 
1d8b0 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79  This is a legacy
1d8c0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
1d8d0 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72  is preserved for
1d8e0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1d8f0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65  tibility..** Use
1d900 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
1d910 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d  ce is not recomm
1d920 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66  ended..**.** Def
1d930 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
1d940 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
1d950 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
1d960 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
1d970 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
1d980 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1d990 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
1d9a0 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
1d9b0 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
1d9c0 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
1d9d0 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
1d9e0 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
1d9f0 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
1da00 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
1da10 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
1da20 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
1da30 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
1da40 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
1da50 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1da60 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
1da70 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
1da80 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
1da90 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
1daa0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1dab0 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
1dac0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1dad0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
1dae0 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
1daf0 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
1db00 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
1db10 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
1db20 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
1db30 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
1db40 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
1db50 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
1db60 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
1db70 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1db80 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
1db90 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
1dba0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
1dbb0 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
1dbc0 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
1dbd0 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
1dbe0 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
1dbf0 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
1dc00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
1dc10 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
1dc20 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
1dc30 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
1dc40 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
1dc50 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
1dc60 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1dc70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
1dc80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
1dc90 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
1dca0 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
1dcb0 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
1dcc0 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
1dcd0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
1dce0 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
1dcf0 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
1dd00 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1dd10 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
1dd20 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
1dd30 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
1dd40 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1dd50 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ble()]..**.** ^(
1dd60 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
1dd70 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1dd80 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
1dd90 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
1dda0 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
1ddb0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1ddc0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1ddd0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
1dde0 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
1ddf0 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
1de00 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
1de10 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
1de20 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
1de30 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
1de40 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
1de50 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
1de60 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1de70 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
1de80 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
1de90 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
1dea0 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
1deb0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
1dec0 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
1ded0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
1dee0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1def0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
1df00 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
1df10 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
1df20 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
1df30 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
1df40 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1df50 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1df60 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
1df70 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
1df80 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
1df90 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
1dfa0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
1dfb0 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
1dfc0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1dfd0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
1dfe0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1dff0 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
1e000 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1e010 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
1e020 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
1e030 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
1e040 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
1e050 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1e060 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
1e070 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1e080 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1e090 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1e0a0 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
1e0b0 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
1e0c0 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
1e0d0 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
1e0e0 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
1e0f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1e100 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
1e110 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
1e120 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
1e130 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
1e140 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
1e150 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
1e160 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
1e170 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
1e180 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
1e190 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
1e1a0 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
1e1b0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
1e1c0 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20  ** it must pass 
1e1d0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1e1e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
1e1f0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1e200 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
1e210 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1e220 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
1e230 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
1e240 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
1e250 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1e260 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
1e270 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
1e280 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
1e290 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
1e2a0 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
1e2b0 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
1e2c0 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
1e2d0 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
1e2e0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
1e2f0 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
1e300 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
1e310 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
1e320 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
1e330 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1e340 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
1e350 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
1e360 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
1e370 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1e380 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
1e390 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
1e3a0 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
1e3b0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
1e3c0 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
1e3d0 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
1e3e0 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
1e3f0 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
1e400 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
1e410 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
1e420 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
1e430 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
1e440 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
1e450 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
1e460 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
1e470 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1e480 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
1e490 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
1e4a0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1e4b0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
1e4c0 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  de()] or.** [sql
1e4d0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
1e4e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1e4f0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
1e500 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
1e510 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
1e520 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
1e530 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1e540 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
1e550 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
1e560 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
1e570 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
1e580 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
1e590 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
1e5a0 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
1e5b0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1e5c0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
1e5d0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
1e5e0 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
1e5f0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1e600 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
1e610 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1e620 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
1e630 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
1e640 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
1e650 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
1e660 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72   void sqlite3_fr
1e670 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
1e680 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
1e690 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
1e6a0 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
1e6b0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1e6c0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1e6d0 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
1e6e0 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
1e6f0 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
1e700 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
1e710 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1e720 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  library..**.** ^
1e730 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
1e740 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
1e750 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
1e760 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
1e770 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
1e780 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
1e790 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
1e7a0 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
1e7b0 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
1e7c0 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
1e7d0 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
1e7e0 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
1e7f0 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
1e800 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69  )].  ^Both routi
1e810 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
1e820 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
1e830 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1e840 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
1e850 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
1e860 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
1e870 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
1e880 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28  string..**.** ^(
1e890 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  The sqlite3_snpr
1e8a0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1e8b0 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
1e8c0 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
1e8d0 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
1e8e0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
1e8f0 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
1e900 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
1e910 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
1e920 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1e930 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
1e940 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
1e950 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1e960 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
1e970 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
1e980 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
1e990 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
1e9a0 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
1e9b0 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61  ().)^  This is a
1e9c0 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
1e9d0 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
1e9e0 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
1e9f0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
1ea00 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
1ea10 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f  atibility.  ^(No
1ea20 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
1ea30 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1ea40 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
1ea50 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
1ea60 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
1ea70 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
1ea80 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
1ea90 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
1eaa0 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57  the buffer.)^  W
1eab0 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
1eac0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
1ead0 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
1eae0 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
1eaf0 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
1eb00 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
1eb10 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
1eb20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1eb30 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1eb40 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
1eb50 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
1eb60 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
1eb70 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74  ** ^As long as t
1eb80 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
1eb90 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
1eba0 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
1ebb0 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
1ebc0 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
1ebd0 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
1ebe0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
1ebf0 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20    ^The first.** 
1ec00 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
1ec10 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
1ec20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
1ec30 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
1ec40 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
1ec50 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
1ec60 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
1ec70 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
1ec80 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
1ec90 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
1eca0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
1ecb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1ecc0 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1ecd0 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20  ne is a varargs 
1ece0 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74  version of sqlit
1ecf0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a  e3_snprintf()..*
1ed00 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1ed10 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e  nes all implemen
1ed20 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  t some additiona
1ed30 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20  l formatting.** 
1ed40 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  options that are
1ed50 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73   useful for cons
1ed60 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61  tructing SQL sta
1ed70 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20  tements..** All 
1ed80 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69  of the usual pri
1ed90 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67  ntf() formatting
1eda0 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20   options apply. 
1edb0 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68   In addition, th
1edc0 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25  ere.** is are "%
1edd0 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25  q", "%Q", and "%
1ede0 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  z" options..**.*
1edf0 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f  * ^(The %q optio
1ee00 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
1ee10 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
1ee20 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72  itutes a nul-ter
1ee30 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1ee40 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
1ee50 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
1ee60 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
1ee70 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
1ee80 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
1ee90 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
1eea0 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
1eeb0 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f  iteral.)^  By do
1eec0 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
1eed0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
1eee0 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
1eef0 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
1ef00 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
1ef10 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
1ef20 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
1ef30 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
1ef40 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
1ef50 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
1ef60 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
1ef70 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1ef80 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1ef90 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
1efa0 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
1efb0 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
1efc0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1efd0 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
1efe0 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
1eff0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
1f000 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1f010 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1f020 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1f030 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1f040 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1f050 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
1f060 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1f070 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1f080 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1f090 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1f0a0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1f0b0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1f0c0 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
1f0d0 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
1f0e0 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
1f0f0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
1f100 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
1f110 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
1f120 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
1f130 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1f140 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1f150 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1f160 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1f170 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
1f180 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
1f190 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1f1a0 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
1f1b0 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
1f1c0 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
1f1d0 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
1f1e0 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
1f1f0 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
1f200 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
1f210 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1f220 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1f230 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1f240 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1f250 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1f260 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1f270 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
1f280 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
1f290 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
1f2a0 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
1f2b0 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
1f2c0 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
1f2d0 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
1f2e0 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
1f2f0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1f300 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  l..**.** ^(The %
1f310 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
1f320 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
1f330 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
1f340 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
1f350 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
1f360 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
1f370 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
1f380 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
1f390 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
1f3a0 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
1f3b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
1f3c0 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
1f3d0 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
1f3e0 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
1f3f0 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c   quotes).)^  So,
1f400 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
1f410 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
1f420 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1f430 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1f440 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1f450 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1f460 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1f470 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
1f480 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1f490 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1f4a0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1f4b0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1f4c0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1f4d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
1f4e0 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
1f4f0 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
1f500 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
1f510 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
1f520 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
1f530 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
1f540 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1f550 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a  .**.** ^(The "%z
1f560 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1f570 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22  ion works like "
1f580 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65  %s" but with the
1f590 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
1f5a0 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
1f5b0 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
1f5c0 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
1f5d0 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
1f5e0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1f5f0 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
1f600 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29  e input string.)
1f610 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ^.*/.SQLITE_API 
1f620 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
1f630 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1f640 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41  *,...);.SQLITE_A
1f650 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
1f660 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1f670 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1f680 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1f690 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1f6a0 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1f6b0 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1f6c0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1f6d0 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e  *sqlite3_vsnprin
1f6e0 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1f6f0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1f700 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1f710 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1f720 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
1f730 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
1f740 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73  e core uses thes
1f750 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
1f760 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
1f770 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
1f780 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f790 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20  n needs. "Core" 
1f7a0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1f7b0 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73  sentence.** does
1f7c0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65   not include ope
1f7d0 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
1f7e0 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65  ecific VFS imple
1f7f0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a  mentation.  The.
1f800 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75  ** Windows VFS u
1f810 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f  ses native mallo
1f820 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
1f830 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f  or some operatio
1f840 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
1f850 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1f860 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1f870 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
1f880 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
1f890 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
1f8a0 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
1f8b0 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
1f8c0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73  ameter..** ^If s
1f8d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1f8e0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
1f8f0 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
1f900 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
1f910 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
1f920 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74   pointer.  ^If t
1f930 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
1f940 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
1f950 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
1f960 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
1f970 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1f980 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
1f990 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1f9a0 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
1f9b0 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
1f9c0 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
1f9d0 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
1f9e0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1f9f0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1fa00 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
1fa10 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
1fa20 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
1fa30 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68   be reused.  ^Th
1fa40 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
1fa50 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
1fa60 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
1fa70 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
1fa80 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
1fa90 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
1faa0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
1fab0 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
1fac0 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
1fad0 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
1fae0 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
1faf0 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
1fb00 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
1fb10 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
1fb20 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
1fb30 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
1fb40 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1fb50 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
1fb60 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
1fb70 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
1fb80 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1fb90 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
1fba0 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
1fbb0 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
1fbc0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1fbd0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
1fbe0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
1fbf0 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
1fc00 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
1fc10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1fc20 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1fc30 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  c()..**.** ^(The
1fc40 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1fc50 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
1fc60 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
1fc70 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
1fc80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
1fc90 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1fca0 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  tes, where N is 
1fcb0 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  the.** second pa
1fcc0 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65  rameter.  The me
1fcd0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1fce0 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73  to be resized is
1fcf0 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
1fd00 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20  rameter.)^ ^ If 
1fd10 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1fd20 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1fd30 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
1fd40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1fd50 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
1fd60 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
1fd70 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1fd80 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65  e3_malloc(N) whe
1fd90 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
1fda0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1fdb0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1fdc0 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65  )..** ^If the se
1fdd0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1fde0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1fdf0 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  c() is zero or.*
1fe00 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
1fe10 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1fe20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
1fe30 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
1fe40 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77  qlite3_free(P) w
1fe50 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69  here P is the fi
1fe60 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1fe70 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1fe80 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  ()..** ^sqlite3_
1fe90 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
1fea0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1feb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1fec0 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1fed0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1fee0 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66  e or NULL if suf
1fef0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
1ff00 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
1ff10 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1ff20 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1ff30 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1ff40 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1ff50 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1ff60 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1ff70 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1ff80 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1ff90 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1ffa0 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1ffb0 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69  oc() and the pri
1ffc0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1ffd0 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73   freed..** ^If s
1ffe0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1fff0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
20000 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c  hen the prior al
20010 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e  location.** is n
20020 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
20030 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75  ^The memory retu
20040 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
20050 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c  malloc() and sql
20060 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
20070 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
20080 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
20090 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
200a0 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
200b0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
200c0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
200d0 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
200e0 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
200f0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
20100 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
20110 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
20120 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
20130 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
20140 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
20150 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
20160 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
20170 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
20180 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
20190 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
201a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
201b0 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
201c0 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
201d0 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
201e0 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
201f0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
20200 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
20210 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
20220 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
20230 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
20240 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
20250 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
20260 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
20270 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
20280 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
20290 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
202a0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
202b0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
202c0 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
202d0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
202e0 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
202f0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
20300 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
20310 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
20320 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
20330 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
20340 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
20350 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
20360 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
20370 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
20380 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
20390 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
203a0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
203b0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
203c0 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
203d0 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
203e0 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
203f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
20400 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
20410 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
20420 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
20430 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
20440 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
20450 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
20460 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
20470 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
20480 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
20490 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
204a0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
204b0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
204c0 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
204d0 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
204e0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
204f0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
20500 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
20510 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
20520 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
20530 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  lloc()]..*/.SQLI
20540 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
20550 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
20560 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
20570 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
20580 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
20590 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
205a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
205b0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
205c0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
205d0 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
205e0 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
205f0 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
20600 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
20610 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
20620 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
20630 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
20640 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
20650 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
20660 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
20670 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
20680 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
20690 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
206a0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
206b0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
206c0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
206d0 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
206e0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
206f0 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
20700 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
20710 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
20720 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
20730 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
20740 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
20750 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
20760 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
20770 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
20780 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
20790 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
207a0 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
207b0 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
207c0 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
207d0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
207e0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
207f0 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
20800 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
20810 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
20820 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
20830 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
20840 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
20850 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
20860 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20870 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
20880 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
20890 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
208a0 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
208b0 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
208c0 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
208d0 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
208e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
208f0 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
20900 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
20910 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
20920 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
20930 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
20940 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
20950 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
20960 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
20970 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
20980 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
20990 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
209a0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
209b0 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
209c0 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
209d0 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
209e0 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
209f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
20a00 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
20a10 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
20a20 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
20a30 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
20a40 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
20a50 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
20a60 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
20a70 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
20a80 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
20a90 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
20aa0 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
20ab0 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
20ac0 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
20ad0 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
20ae0 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
20af0 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
20b00 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
20b10 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
20b20 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
20b30 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
20b40 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
20b50 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
20b60 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
20b70 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
20b80 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
20b90 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
20ba0 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
20bb0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
20bc0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
20bd0 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
20be0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
20bf0 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
20c00 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
20c10 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
20c20 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
20c30 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
20c40 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
20c50 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ffer P..**.** ^T
20c60 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
20c70 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
20c80 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
20c90 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
20ca0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
20cb0 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
20cc0 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
20cd0 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
20ce0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
20cf0 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
20d00 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
20d10 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
20d20 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73  ct..** ^On all s
20d30 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
20d40 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
20d50 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
20d60 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
20d70 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
20d80 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
20d90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
20da0 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
20db0 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49   method..*/.SQLI
20dc0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
20dd0 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
20de0 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
20df0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20e00 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
20e10 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
20e20 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  backs.**.** ^Thi
20e30 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
20e40 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ers an authorize
20e50 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
20e60 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
20e70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
20e80 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
20e90 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
20ea0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
20eb0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20ec0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
20ed0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
20ee0 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
20ef0 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
20f00 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
20f10 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
20f20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20f30 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
20f40 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
20f50 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
20f60 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
20f70 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
20f80 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
20f90 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
20fa0 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
20fb0 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
20fc0 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
20fd0 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
20fe0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20ff0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
21000 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
21010 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
21020 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
21030 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21040 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
21050 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
21060 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
21070 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
21080 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
21090 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
210a0 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
210b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
210c0 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
210d0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
210e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
210f0 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
21100 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
21110 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
21120 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
21130 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
21140 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21150 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
21160 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
21170 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
21180 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
21190 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
211a0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
211b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
211c0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
211d0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
211e0 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
211f0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
21200 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
21210 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
21220 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
21230 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
21240 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
21250 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
21260 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
21270 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
21280 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
21290 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
212a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
212b0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
212c0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
212d0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
212e0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
212f0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
21300 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
21310 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
21320 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
21330 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
21340 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
21350 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
21360 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
21370 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
21380 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
21390 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
213a0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
213b0 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
213c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
213d0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
213e0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
213f0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
21400 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
21410 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
21420 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
21430 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
21440 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
21450 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
21460 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
21470 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
21480 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
21490 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
214a0 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
214b0 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
214c0 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
214d0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
214e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
214f0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
21500 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
21510 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
21520 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
21530 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
21540 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
21550 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
21560 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
21570 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
21580 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
21590 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
215a0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
215b0 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
215c0 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
215d0 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
215e0 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
215f0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
21600 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
21610 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
21620 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
21630 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
21640 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
21650 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
21660 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
21670 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
21680 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
21690 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
216a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
216b0 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
216c0 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
216d0 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
216e0 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
216f0 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
21700 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
21710 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
21720 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
21730 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
21740 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
21750 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
21760 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
21770 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
21780 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
21790 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
217a0 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
217b0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
217c0 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
217d0 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
217e0 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
217f0 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
21800 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
21810 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
21820 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
21830 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
21840 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
21850 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
21860 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
21870 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
21880 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
21890 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
218a0 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
218b0 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
218c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
218d0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
218e0 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
218f0 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
21900 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
21910 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
21920 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
21930 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
21940 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
21950 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
21960 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
21970 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
21980 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
21990 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
219a0 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
219b0 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
219c0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
219d0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
219e0 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
219f0 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
21a00 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
21a10 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
21a20 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
21a30 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
21a40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
21a50 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
21a60 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
21a70 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
21a80 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
21a90 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
21aa0 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
21ab0 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
21ac0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
21ad0 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
21ae0 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
21af0 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
21b00 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
21b10 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
21b20 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
21b30 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
21b40 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
21b50 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
21b60 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
21b70 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
21b80 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
21b90 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
21ba0 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
21bb0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
21bc0 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
21bd0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
21be0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
21bf0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
21c00 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
21c10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
21c20 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
21c30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21c40 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
21c50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21c60 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
21c70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
21c80 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
21c90 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
21ca0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
21cb0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
21cc0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
21cd0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
21ce0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
21cf0 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
21d00 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
21d10 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
21d20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
21d30 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
21d40 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
21d50 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
21d60 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
21d70 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
21d80 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
21d90 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
21da0 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
21db0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21dc0 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
21dd0 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
21de0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
21df0 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
21e00 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
21e10 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
21e20 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
21e30 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
21e40 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
21e50 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
21e60 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
21e70 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
21e80 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
21e90 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
21ea0 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
21eb0 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
21ec0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
21ed0 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
21ee0 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
21ef0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
21f00 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
21f10 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
21f20 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
21f30 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49   change..*/.SQLI
21f40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
21f50 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
21f60 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
21f70 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
21f80 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
21f90 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
21fa0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
21fb0 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
21fc0 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
21fd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21fe0 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
21ff0 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
22000 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
22010 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
22020 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
22030 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
22040 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
22050 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
22060 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
22070 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
22080 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
22090 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
220a0 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
220b0 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
220c0 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
220d0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
220e0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
220f0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
22100 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
22110 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
22120 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
22130 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61  LITE_IGNORE is a
22140 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53  lso used as a [S
22150 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c  QLITE_ROLLBACK |
22160 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a   return code].**
22170 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
22180 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
22190 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
221a0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
221b0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
221c0 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
221d0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
221e0 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
221f0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
22200 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
22210 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
22220 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
22230 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
22240 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
22250 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
22260 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
22270 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
22280 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
22290 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
222a0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
222b0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
222c0 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
222d0 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
222e0 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
222f0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
22300 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
22310 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
22320 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
22330 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
22340 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
22350 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
22360 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
22370 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
22380 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
22390 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
223a0 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
223b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
223c0 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
223d0 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
223e0 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
223f0 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
22400 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
22410 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
22420 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
22430 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
22440 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
22450 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
22460 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
22470 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
22480 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
22490 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
224a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
224b0 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
224c0 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
224d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
224e0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
224f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
22500 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
22510 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
22520 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
22530 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
22540 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
22550 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
22560 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
22570 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
22580 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
22590 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
225a0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
225b0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
225c0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
225d0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
225e0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
225f0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
22600 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
22610 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22620 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
22630 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
22640 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
22650 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22660 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
22670 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
22680 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
22690 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
226a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
226b0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
226c0 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
226d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
226e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
226f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22700 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
22710 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
22720 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
22730 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
22740 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
22750 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
22760 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
22770 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
22780 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22790 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
227a0 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
227b0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
227c0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
227d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
227e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
227f0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
22800 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
22810 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22820 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22830 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22840 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
22850 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
22860 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
22870 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22880 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
22890 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
228a0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
228b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
228c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
228d0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
228e0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
228f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22900 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22910 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22920 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
22930 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
22940 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
22950 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22960 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22970 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
22980 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
22990 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
229a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
229b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
229c0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
229d0 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
229e0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
229f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22a00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22a10 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
22a20 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
22a30 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22a40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22a50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22a60 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
22a70 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
22a80 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
22a90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22aa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22ab0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
22ac0 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
22ad0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
22ae0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22af0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22b00 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
22b10 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
22b20 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
22b30 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22b40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22b50 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
22b60 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
22b70 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
22b80 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22b90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
22ba0 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
22bb0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
22bc0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22bd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22be0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
22bf0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
22c00 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
22c10 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
22c20 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
22c30 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
22c40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22c50 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
22c60 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
22c70 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
22c80 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
22c90 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
22ca0 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
22cb0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
22cc0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22cd0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
22ce0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
22cf0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
22d00 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22d10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22d20 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
22d30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
22d40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22d50 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
22d60 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
22d70 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
22d80 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
22d90 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
22da0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22db0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22dc0 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
22dd0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
22de0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
22df0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
22e00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22e10 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
22e20 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
22e30 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
22e40 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22e50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22e60 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
22e70 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
22e80 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
22e90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22ea0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22eb0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
22ec0 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
22ed0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22ee0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22ef0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22f00 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
22f10 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
22f20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22f30 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
22f40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22f50 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
22f60 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
22f70 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
22f80 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
22f90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22fa0 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
22fb0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
22fc0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
22fd0 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
22fe0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22ff0 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
23000 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
23010 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
23020 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
23030 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
23040 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
23050 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
23060 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f  onger used */../
23070 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
23080 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
23090 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
230a0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
230b0 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
230c0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
230d0 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
230e0 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
230f0 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
23100 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
23110 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
23120 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
23130 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
23140 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
23150 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
23160 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
23170 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
23180 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
23190 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
231a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
231b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
231c0 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
231d0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
231e0 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
231f0 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
23200 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
23210 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
23220 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
23230 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
23240 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
23250 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
23260 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
23270 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
23280 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
23290 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
232a0 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
232b0 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
232c0 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
232d0 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
232e0 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
232f0 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er.)^.**.** ^The
23300 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
23310 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
23320 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
23330 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
23340 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
23350 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
23360 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
23370 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
23380 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
23390 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
233a0 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
233b0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
233c0 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
233d0 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
233e0 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
233f0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
23400 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
23410 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
23420 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
23430 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
23440 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
23450 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
23460 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
23470 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
23480 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
23490 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
234a0 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
234b0 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
234c0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
234d0 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
234e0 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
234f0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
23500 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
23510 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
23520 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
23530 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
23540 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
23550 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
23560 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
23570 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
23580 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
23590 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
235a0 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
235b0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
235c0 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
235d0 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
235e0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
235f0 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
23600 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
23610 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
23620 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
23630 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
23640 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
23650 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
23660 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23670 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
23680 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
23690 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72   ^The sqlite3_pr
236a0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44  ogress_handler(D
236b0 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,N,X,P) interfac
236c0 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  e causes the cal
236d0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
236e0 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n X to be invoke
236f0 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
23700 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
23710 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ng calls to.** [
23720 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
23730 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23740 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67  ] and [sqlite3_g
23750 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a  et_table()] for.
23760 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
23770 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78  ection D.  An ex
23780 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
23790 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
237a0 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
237b0 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
237c0 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
237d0 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65  *.** ^The parame
237e0 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20  ter P is passed 
237f0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f  through as the o
23800 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
23810 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63   the .** callbac
23820 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e  k function X.  ^
23830 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  The parameter N 
23840 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
23850 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61   .** [virtual ma
23860 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f  chine instructio
23870 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61  ns] that are eva
23880 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73  luated between s
23890 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76  uccessive.** inv
238a0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
238b0 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a  callback X..**.*
238c0 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
238d0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
238e0 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
238f0 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
23900 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
23910 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
23920 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
23930 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
23940 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
23950 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
23960 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
23970 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
23980 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
23990 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
239a0 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
239b0 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
239c0 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
239d0 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
239e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
239f0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
23a00 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
23a10 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
23a20 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
23a30 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
23a40 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
23a50 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
23a60 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
23a70 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
23a80 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
23a90 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
23aa0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
23ab0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
23ac0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
23ad0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
23ae0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23af0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
23b00 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
23b10 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
23b20 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
23b30 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
23b40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
23b50 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
23b60 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
23b70 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
23b80 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
23b90 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
23ba0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51  agraph..**.*/.SQ
23bb0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
23bc0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
23bd0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
23be0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
23bf0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
23c00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
23c10 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
23c20 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
23c30 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
23c40 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
23c50 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
23c60 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
23c70 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
23c80 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
23c90 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
23ca0 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
23cb0 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
23cc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
23cd0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
23ce0 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
23cf0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
23d00 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
23d10 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
23d20 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
23d30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23d40 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
23d50 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
23d60 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
23d70 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
23d80 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
23d90 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
23da0 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
23db0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
23dc0 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
23dd0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
23de0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
23df0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
23e00 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
23e10 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
23e20 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
23e30 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
23e40 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
23e50 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
23e60 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
23e70 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
23e80 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
23e90 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
23ea0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
23eb0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
23ec0 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
23ed0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
23ee0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
23ef0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
23f00 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
23f10 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
23f20 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
23f30 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
23f40 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
23f50 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
23f60 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
23f70 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
23f80 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
23f90 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
23fa0 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
23fb0 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
23fc0 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
23fd0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
23fe0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
23ff0 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
24000 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
24010 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
24020 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
24030 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
24040 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
24050 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
24060 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
24070 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
24080 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
24090 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
240a0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
240b0 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
240c0 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
240d0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
240e0 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
240f0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
24100 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
24110 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24120 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
24130 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
24140 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
24150 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
24160 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
24170 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
24180 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
24190 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
241a0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
241b0 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
241c0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
241d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
241e0 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
241f0 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
24200 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
24210 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
24220 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
24230 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
24240 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
24250 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
24260 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
24270 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
24280 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
24290 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
242a0 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
242b0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
242c0 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
242d0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
242e0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
242f0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
24300 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
24310 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
24320 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
24330 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
24340 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
24350 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
24360 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
24370 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
24380 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
24390 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
243a0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
243b0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
243c0 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
243d0 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
243e0 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
243f0 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
24400 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
24410 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
24420 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
24430 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
24440 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
24450 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
24460 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
24470 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
24480 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
24490 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
244a0 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
244b0 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
244c0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
244d0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
244e0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
244f0 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
24500 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
24510 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
24520 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
24530 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
24540 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
24550 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
24560 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
24570 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
24580 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
24590 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
245a0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
245b0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
245c0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
245d0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
245e0 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
245f0 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
24600 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
24610 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
24620 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
24630 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
24640 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
24650 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
24660 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
24670 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
24680 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
24690 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
246a0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
246b0 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
246c0 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
246d0 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
246e0 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
246f0 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
24700 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
24710 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
24720 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
24730 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
24740 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
24750 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
24760 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24770 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
24780 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
24790 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
247a0 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
247b0 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
247c0 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
247d0 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
247e0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
247f0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
24800 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
24810 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
24820 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
24830 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
24840 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
24850 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
24860 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
24870 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
24880 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
24890 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
248a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
248b0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
248c0 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
248d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
248e0 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
248f0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
24900 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
24910 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
24920 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
24930 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
24940 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
24950 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
24960 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
24970 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24980 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
24990 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
249a0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
249b0 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
249c0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
249d0 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
249e0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
249f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
24a00 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
24a10 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
24a20 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
24a30 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
24a40 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
24a50 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
24a60 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
24a70 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
24a80 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
24a90 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
24aa0 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
24ab0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
24ac0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
24ad0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
24ae0 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
24af0 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
24b00 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
24b10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24b20 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
24b30 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
24b40 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
24b50 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
24b60 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
24b70 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
24b80 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
24b90 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
24ba0 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
24bb0 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
24bc0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
24bd0 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
24be0 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
24bf0 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
24c00 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
24c10 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
24c20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
24c30 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
24c40 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
24c50 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
24c60 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
24c70 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
24c80 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
24c90 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
24ca0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
24cb0 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
24cc0 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
24cd0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
24ce0 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
24cf0 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
24d00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24d10 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
24d20 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
24d30 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
24d40 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
24d50 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
24d60 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
24d70 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
24d80 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
24d90 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
24da0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
24db0 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
24dc0 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
24dd0 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
24de0 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
24df0 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
24e00 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
24e10 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
24e20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
24e30 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
24e40 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72   set in the four
24e50 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
24e60 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24e70 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
24e80 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
24e90 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
24ea0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
24eb0 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
24ec0 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
24ed0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
24ee0 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
24ef0 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
24f00 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
24f10 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69  n..** As of SQLi
24f20 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
24f30 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  , URI filename i
24f40 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
24f50 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
24f60 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
24f70 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
24f80 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
24f90 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
24fa0 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
24fb0 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
24fc0 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
24fd0 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
24fe0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
24ff0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
25000 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
25010 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
25020 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
25030 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
25040 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
25050 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
25060 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
25070 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
25080 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
25090 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
250a0 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
250b0 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
250c0 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
250d0 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
250e0 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
250f0 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
25100 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
25110 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
25120 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
25130 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
25140 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
25150 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
25160 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
25170 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
25180 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
25190 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
251a0 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
251b0 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
251c0 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
251d0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
251e0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
251f0 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
25200 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
25210 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
25220 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
25230 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
25240 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
25250 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
25260 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
25270 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
25280 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
25290 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
252a0 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  ^On windows, the
252b0 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
252c0 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
252d0 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
252e0 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
252f0 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a  n (e.g. "C:")..*
25300 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20  *.** [[core URI 
25310 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
25320 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20  ]].** The query 
25330 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
25340 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70  RI may contain p
25350 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
25360 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a  re interpreted.*
25370 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69  * either by SQLi
25380 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79  te itself, or by
25390 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d   a [VFS | custom
253a0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
253b0 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ion]..** SQLite 
253c0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 66  interprets the f
253d0 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71  ollowing three q
253e0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
253f0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
25400 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
25410 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
25420 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
25430 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
25440 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
25450 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
25460 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
25470 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
25480 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
25490 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
254a0 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
254b0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
254c0 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
254d0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
254e0 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
254f0 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
25500 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
25510 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
25520 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
25530 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
25540 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
25550 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25560 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
25570 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
25580 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
25590 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
255a0 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
255b0 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
255c0 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
255d0 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
255e0 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
255f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
25600 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
25610 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
25620 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
25630 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
25640 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
25650 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a  her "ro", "rw",.
25660 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72  **     "rwc", or
25670 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d   "memory". Attem
25680 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20  pting to set it 
25690 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c  to any other val
256a0 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20  ue is.**     an 
256b0 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
256c0 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
256d0 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
256e0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
256f0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
25700 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
25710 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
25720 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
25730 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
25740 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
25750 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
25760 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
25770 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49  e3_open_v2(). ^I
25780 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
25790 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
257a0 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
257b0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
257c0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
257d0 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
257e0 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
257f0 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
25800 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
25810 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
25820 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
25830 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
25840 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
25850 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
25860 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
25870 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
25880 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
25890 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
258a0 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
258b0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
258c0 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
258d0 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
258e0 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
258f0 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
25900 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
25910 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
25920 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
25930 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
25940 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
25950 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
25960 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
25970 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
25980 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
25990 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
259a0 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
259b0 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
259c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
259d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
259e0 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
259f0 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
25a00 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
25a10 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
25a20 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
25a30 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
25a40 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
25a50 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
25a60 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
25a70 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
25a80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
25a90 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
25aa0 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
25ab0 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
25ac0 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
25ad0 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
25ae0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
25af0 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
25b00 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
25b10 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
25b20 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
25b30 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
25b40 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
25b50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
25b60 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
25b70 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
25b80 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
25b90 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
25ba0 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
25bb0 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
25bc0 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65  ehavior requeste
25bd0 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
25be0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
25bf0 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
25c00 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
25c10 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
25c20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
25c30 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
25c40 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
25c50 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
25c60 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
25c70 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
25c80 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
25c90 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
25ca0 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
25cb0 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
25cc0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
25cd0 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
25ce0 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
25cf0 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
25d00 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
25d10 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
25d20 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
25d30 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
25d40 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
25d50 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
25d60 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
25d70 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
25d80 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
25d90 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
25da0 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
25db0 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
25dc0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
25dd0 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
25de0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
25df0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
25e00 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
25e10 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
25e20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
25e30 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
25e40 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
25e50 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
25e60 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
25e70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
25e80 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
25e90 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
25ea0 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
25eb0 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
25ec0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
25ed0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
25ee0 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
25ef0 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
25f00 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
25f10 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
25f20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
25f30 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
25f40 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
25f50 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
25f60 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
25f70 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
25f80 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
25f90 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
25fa0 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
25fb0 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
25fc0 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
25fd0 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
25fe0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
25ff0 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
26000 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
26010 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
26020 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
26030 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
26040 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
26050 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
26060 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
26070 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
26080 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
26090 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
260a0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
260b0 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
260c0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
260d0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
260e0 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
260f0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
26100 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
26110 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
26120 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
26130 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
26140 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
26150 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
26160 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
26170 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
26180 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
26190 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
261a0 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
261b0 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
261c0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
261d0 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
261e0 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20  -nolock <td>.** 
261f0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
26200 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
26210 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65  ata.db". Use the
26220 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e   special VFS "un
26230 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c  ix-nolock"..** <
26240 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
26250 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e  a.db?mode=readon
26260 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  ly <td> .**     
26270 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
26280 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74  readonly" is not
26290 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20   a valid option 
262a0 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70  for the "mode" p
262b0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74  arameter..** </t
262c0 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49  able>.**.** ^URI
262d0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
262e0 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25  ape sequences (%
262f0 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65  HH) are supporte
26300 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74  d within the pat
26310 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63  h and.** query c
26320 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55  omponents of a U
26330 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61  RI. A hexadecima
26340 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
26350 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a  e consists of a.
26360 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20  ** percent sign 
26370 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64  - "%" - followed
26380 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20   by exactly two 
26390 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69  hexadecimal digi
263a0 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e  ts .** specifyin
263b0 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65  g an octet value
263c0 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61  . ^Before the pa
263d0 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70  th or query comp
263e0 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55  onents of a.** U
263f0 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20  RI filename are 
26400 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65  interpreted, the
26410 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73  y are encoded us
26420 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c  ing UTF-8 and al
26430 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61  l .** hexadecima
26440 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
26450 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  es replaced by a
26460 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e   single byte con
26470 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
26480 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74  orresponding oct
26490 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63  et. If this proc
264a0 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e  ess generates an
264b0 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65   invalid UTF-8 e
264c0 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  ncoding,.** the 
264d0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
264e0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  fined..**.** <b>
264f0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
26500 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
26510 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
26520 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
26530 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
26540 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
26550 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26560 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
26570 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
26580 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
26590 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
265a0 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
265b0 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
265c0 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
265d0 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
265e0 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
265f0 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
26600 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
26610 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
26620 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
26630 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
26640 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  o Windows Runtim
26650 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  e users:</b>  Th
26660 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65  e temporary dire
26670 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65  ctory must be se
26680 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  t.** prior to ca
26690 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  lling sqlite3_op
266a0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
266b0 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65  open_v2().  Othe
266c0 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a  rwise, various.*
266d0 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20  * features that 
266e0 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20  require the use 
266f0 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  of temporary fil
26700 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a  es may fail..**.
26710 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
26720 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
26730 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tory].*/.SQLITE_
26740 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
26750 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
26760 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
26770 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
26780 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
26790 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
267a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
267b0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
267c0 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  le */.);.SQLITE_
267d0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
267e0 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
267f0 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
26800 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
26810 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
26820 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
26830 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
26840 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
26850 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49  andle */.);.SQLI
26860 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
26870 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
26880 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
26890 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
268a0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
268b0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
268c0 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
268d0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
268e0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
268f0 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
26900 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
26910 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
26920 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
26930 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
26940 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
26950 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26960 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f  Obtain Values Fo
26970 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73  r URI Parameters
26980 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
26990 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65   utility routine
269a0 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53  s, useful to VFS
269b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
269c0 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20  , that check.** 
269d0 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61  to see if a data
269e0 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20  base file was a 
269f0 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  URI that contain
26a00 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75  ed a specific qu
26a10 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ery .** paramete
26a20 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74  r, and if so obt
26a30 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  ains the value o
26a40 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72  f that query par
26a50 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
26a60 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61   F is the databa
26a70 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e  se filename poin
26a80 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ter passed into 
26a90 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68  the xOpen() meth
26aa0 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20  od of .** a VFS 
26ab0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
26ac0 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61  hen the flags pa
26ad0 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
26ae0 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a  () has one or .*
26af0 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53  * more of the [S
26b00 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
26b10 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
26b20 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65  MAIN_DB] bits se
26b30 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68  t and.** P is th
26b40 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75  e name of the qu
26b50 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ery parameter, t
26b60 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  hen.** sqlite3_u
26b70 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
26b80 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  ) returns the va
26b90 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20  lue of the P.** 
26ba0 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20  parameter if it 
26bb0 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c  exists or a NULL
26bc0 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f   pointer if P do
26bd0 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73  es not appear as
26be0 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   a .** query par
26bf0 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66  ameter on F.  If
26c00 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61   P is a query pa
26c10 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20  rameter of F.** 
26c20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20  has no explicit 
26c30 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69  value, then sqli
26c40 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
26c50 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a  r(F,P) returns.*
26c60 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
26c70 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
26c80 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
26c90 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
26ca0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73  P,B) routine ass
26cb0 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61  umes that P is a
26cc0 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61   boolean.** para
26cd0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
26ce0 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61  s true (1) or fa
26cf0 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e  lse (0) accordin
26d00 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a  g to the value.*
26d10 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c  * of P.  The sql
26d20 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
26d30 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
26d40 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
26d50 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65   if the.** value
26d60 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65   of query parame
26d70 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
26d80 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f  "yes", "true", o
26d90 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a  r "on" in any.**
26da0 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20   case or if the 
26db0 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
26dc0 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d  h a non-zero num
26dd0 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71  ber.  The .** sq
26de0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
26df0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
26e00 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  s returns false 
26e10 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65  (0) if the value
26e20 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   of.** query par
26e30 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
26e40 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22  of "no", "false"
26e50 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e  , or "off" in an
26e60 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20  y case or.** if 
26e70 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
26e80 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20   with a numeric 
26e90 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e  zero.  If P is n
26ea0 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61  ot a query.** pa
26eb0 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20  rameter on F or 
26ec0 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  if the value of 
26ed0 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61  P is does not ma
26ee0 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a  tch any of the.*
26ef0 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71  * above, then sq
26f00 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
26f10 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
26f20 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54   (B!=0)..**.** T
26f30 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  he sqlite3_uri_i
26f40 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74  nt64(F,P,D) rout
26f50 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ine converts the
26f60 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f   value of P into
26f70 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67   a.** 64-bit sig
26f80 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
26f90 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74  returns that int
26fa0 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20  eger, or D if P 
26fb0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73  does not.** exis
26fc0 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65  t.  If the value
26fd0 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69   of P is somethi
26fe0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e  ng other than an
26ff0 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a   integer, then.*
27000 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  * zero is return
27010 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20  ed..** .** If F 
27020 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
27030 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
27040 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
27050 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  P) returns NULL 
27060 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  and.** sqlite3_u
27070 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
27080 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66  ) returns B.  If
27090 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c   F is not a NULL
270a0 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20   pointer and.** 
270b0 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
270c0 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  e file pathname 
270d0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c  pointer that SQL
270e0 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ite passed into 
270f0 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53  the xOpen.** VFS
27100 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
27110 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
27120 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e  is routine is un
27130 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
27140 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61  ably.** undesira
27150 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ble..*/.SQLITE_A
27160 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
27170 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
27180 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
27190 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
271a0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
271b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
271c0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
271d0 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
271e0 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
271f0 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
27200 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45  Default);.SQLITE
27210 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
27220 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  64 sqlite3_uri_i
27230 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a  nt64(const char*
27240 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
27250 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
27260 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27270 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
27280 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20   Messages.**.** 
27290 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
272a0 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65  code() interface
272b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
272c0 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
272d0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
272e0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
272f0 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
27300 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
27310 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a  e3_* API call.**
27320 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
27330 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
27340 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70  nection]. If a p
27350 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
27360 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20  iled.** but the 
27370 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
27380 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
27390 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
273a0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
273b0 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
273c0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73  defined.  ^The s
273d0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
273e0 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74  errcode().** int
273f0 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61  erface is the sa
27400 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69  me except that i
27410 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
27420 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64   the .** [extend
27430 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
27440 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64  even when extend
27450 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
27460 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  are.** disabled.
27470 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27480 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
27490 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
274a0 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
274b0 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
274c0 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
274d0 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
274e0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
274f0 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
27500 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
27510 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
27520 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
27530 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
27540 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
27550 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
27560 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
27570 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
27580 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
27590 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
275a0 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
275b0 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
275c0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
275d0 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
275e0 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
275f0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
27600 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
27610 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27620 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61  errstr() interfa
27630 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45  ce returns the E
27640 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20  nglish-language 
27650 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73  text.** that des
27660 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75  cribes the [resu
27670 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46  lt code], as UTF
27680 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  -8..** ^(Memory 
27690 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
276a0 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
276b0 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
276c0 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75  rnally.** and mu
276d0 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20  st not be freed 
276e0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
276f0 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  on)^..**.** When
27700 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
27710 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
27720 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
27730 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
27740 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
27750 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
27760 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
27770 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
27780 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
27790 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
277a0 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
277b0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
277c0 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
277d0 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
277e0 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
277f0 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
27800 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
27810 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
27820 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
27830 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
27840 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
27850 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
27860 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
27870 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
27880 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
27890 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
278a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
278b0 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
278c0 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
278d0 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
278e0 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
278f0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
27900 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
27910 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
27920 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
27930 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
27940 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
27950 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
27960 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
27970 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
27980 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
27990 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
279a0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
279b0 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
279c0 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
279d0 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
279e0 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
279f0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
27a00 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
27a10 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f  y not be set..*/
27a20 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
27a30 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
27a40 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51  sqlite3 *db);.SQ
27a50 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
27a60 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
27a70 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
27a80 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  b);.SQLITE_API c
27a90 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
27aa0 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
27ab0 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
27ac0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
27ad0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
27ae0 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  ite3*);.SQLITE_A
27af0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
27b00 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
27b10 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
27b20 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
27b30 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
27b40 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
27b50 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
27b60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
27b70 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
27b80 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
27b90 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
27ba0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
27bb0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
27bc0 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
27bd0 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
27be0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27bf0 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
27c00 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
27c10 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
27c20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
27c30 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
27c40 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
27c50 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
27c60 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
27c70 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
27c80 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
27c90 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
27ca0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
27cb0 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
27cc0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
27cd0 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
27ce0 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
27cf0 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
27d00 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
27d10 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
27d20 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
27d30 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
27d40 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
27d50 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
27d60 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
27d70 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
27d80 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
27d90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
27da0 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
27db0 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
27dc0 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
27dd0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
27de0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
27df0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
27e00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
27e10 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
27e20 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
27e30 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
27e40 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
27e50 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
27e60 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
27e70 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
27e80 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
27e90 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
27ea0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27eb0 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
27ec0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
27ed0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
27ee0 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
27ef0 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
27f00 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
27f10 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
27f20 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
27f30 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
27f40 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
27f50 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
27f60 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
27f70 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
27f80 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
27f90 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
27fa0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
27fb0 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
27fc0 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
27fd0 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
27fe0 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
27ff0 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
28000 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
28010 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
28020 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
28030 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a  at construct.)^.
28040 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65  **.** ^If the ne
28050 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
28060 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
28070 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
28080 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65  nged..** ^(For e
28090 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ach limit catego
280a0 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ry SQLITE_LIMIT_
280b0 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72  <i>NAME</i> ther
280c0 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69  e is a .** [limi
280d0 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20  ts | hard upper 
280e0 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74  bound].** set at
280f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79   compile-time by
28100 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f   a C preprocesso
28110 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a  r macro called.*
28120 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49  * [limits | SQLI
28130 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f  TE_MAX_<i>NAME</
28140 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  i>]..** (The "_L
28150 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
28160 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
28170 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20   "_MAX_".))^.** 
28180 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63  ^Attempts to inc
28190 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
281a0 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
281b0 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
281c0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
281d0 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
281e0 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a  pper bound..**.*
281f0 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66  * ^Regardless of
28200 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
28210 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68  the limit was ch
28220 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b  anged, the .** [
28230 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
28240 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
28250 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ns the prior val
28260 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e  ue of the limit.
28270 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66  .** ^Hence, to f
28280 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  ind the current 
28290 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74  value of a limit
282a0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e   without changin
282b0 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20  g it,.** simply 
282c0 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65  invoke this inte
282d0 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74  rface with the t
282e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73  hird parameter s
282f0 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20  et to -1..**.** 
28300 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
28310 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
28320 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
28330 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
28340 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
28350 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
28360 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
28370 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
28380 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
28390 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
283a0 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
283b0 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
283c0 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
283d0 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
283e0 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
283f0 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
28400 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
28410 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
28420 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
28430 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
28440 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
28450 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
28460 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
28470 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
28480 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
28490 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
284a0 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
284b0 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
284c0 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
284d0 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
284e0 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
284f0 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
28500 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
28510 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
28520 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
28530 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
28540 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
28550 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
28560 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
28570 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
28580 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
28590 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
285a0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
285b0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
285c0 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
285d0 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
285e0 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
285f0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
28600 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
28610 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
28620 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
28630 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
28640 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
28650 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51   releases..*/.SQ
28660 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28670 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
28680 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
28690 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
286a0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
286b0 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
286c0 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
286d0 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
286e0 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
286f0 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
28700 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
28710 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
28720 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
28730 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
28740 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
28750 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
28760 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
28770 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
28780 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
28790 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
287a0 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
287b0 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
287c0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
287d0 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
287e0 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
287f0 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
28800 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  l>.** [[SQLITE_L
28810 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  IMIT_LENGTH]] ^(
28820 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28830 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
28840 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
28850 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
28860 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
28870 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65  ble row, in byte
28880 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  s.<dd>)^.**.** [
28890 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  [SQLITE_LIMIT_SQ
288a0 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  L_LENGTH]] ^(<dt
288b0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
288c0 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
288d0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
288e0 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
288f0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20  L statement, in 
28900 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  bytes.</dd>)^.**
28910 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
28920 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64  IT_COLUMN]] ^(<d
28930 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
28940 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
28950 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
28960 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
28970 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
28980 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
28990 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
289a0 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
289b0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
289c0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
289d0 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
289e0 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
289f0 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
28a00 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
28a10 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  [SQLITE_LIMIT_EX
28a20 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  PR_DEPTH]] ^(<dt
28a30 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
28a40 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
28a50 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
28a60 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
28a70 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
28a80 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
28a90 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
28aa0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
28ab0 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e  _SELECT]] ^(<dt>
28ac0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
28ad0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
28ae0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
28af0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
28b00 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
28b10 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
28b20 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
28b30 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
28b40 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74  _VDBE_OP]] ^(<dt
28b50 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
28b60 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
28b70 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
28b80 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
28b90 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
28ba0 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
28bb0 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
28bc0 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
28bd0 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c  atement.  This l
28be0 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72  imit is not curr
28bf0 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65  ently.** enforce
28c00 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d  d, though that m
28c10 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e  ight be added in
28c20 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
28c30 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
28c40 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
28c50 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  [[SQLITE_LIMIT_F
28c60 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28  UNCTION_ARG]] ^(
28c70 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28c80 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
28c90 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
28ca0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
28cb0 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
28cc0 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
28cd0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
28ce0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20  IMIT_ATTACHED]] 
28cf0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
28d00 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
28d10 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28d20 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41  mum number of [A
28d30 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64  TTACH | attached
28d40 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f   databases].)^</
28d50 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
28d60 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
28d70 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a  TTERN_LENGTH]].*
28d80 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
28d90 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
28da0 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
28db0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
28dc0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
28dd0 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
28de0 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72  to the [LIKE] or
28df0 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  .** [GLOB] opera
28e00 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tors.</dd>)^.**.
28e10 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
28e20 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
28e30 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  R]].** ^(<dt>SQL
28e40 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
28e50 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
28e60 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
28e70 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f  m index number o
28e80 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72  f any [parameter
28e90 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  ] in an SQL stat
28ea0 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  ement.)^.**.** [
28eb0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  [SQLITE_LIMIT_TR
28ec0 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28  IGGER_DEPTH]] ^(
28ed0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28ee0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
28ef0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
28f00 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
28f10 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
28f20 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
28f30 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
28f40 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
28f50 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
28f60 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
28f70 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
28f80 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
28f90 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
28fa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
28fb0 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
28fc0 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
28fd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
28fe0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
28ff0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
29000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29010 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
29020 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
29030 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29040 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
29050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
29060 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29070 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
29080 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
29090 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
290a0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
290b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
290c0 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
290d0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
290e0 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20  TERN_LENGTH     
290f0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
29100 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
29110 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20  E_NUMBER        
29120 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
29130 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
29140 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
29150 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     10../*.** CAP
29160 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
29170 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
29180 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
29190 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
291a0 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f  mpiler}.**.** To
291b0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
291c0 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
291d0 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
291e0 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
291f0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
29200 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
29210 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
29220 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
29230 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
29240 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29250 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
29260 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
29270 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
29280 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
29290 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
292a0 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
292b0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
292c0 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
292d0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
292e0 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
292f0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
29300 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
29310 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
29320 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
29330 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
29340 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
29350 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
29360 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
29370 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
29380 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
29390 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
293a0 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
293b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
293c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
293d0 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
293e0 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
293f0 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
29400 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74  gument is less t
29410 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a  han zero, then z
29420 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
29430 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
29440 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
29450 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  ^If nByte is non
29460 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
29470 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  it is the maximu
29480 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20  m.** number of  
29490 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
294a0 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79  zSql.  ^When nBy
294b0 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
294c0 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20  ve, the.** zSql 
294d0 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65  string ends at e
294e0 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20  ither the first 
294f0 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30  '\000' or '\u000
29500 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a  0' character or.
29510 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20  ** the nByte-th 
29520 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20  byte, whichever 
29530 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20  comes first. If 
29540 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
29550 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70  .** that the sup
29560 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
29570 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
29580 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20  then there is a 
29590 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d  small.** perform
295a0 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
295b0 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70  o be gained by p
295c0 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
295d0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
295e0 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68  * is equal to th
295f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
29600 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
29610 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
29620 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
29630 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74  l-terminator byt
29640 65 73 20 61 73 20 74 68 69 73 20 73 61 76 65 73  es as this saves
29650 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76   SQLite from hav
29660 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61  ing to.** make a
29670 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70   copy of the inp
29680 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ut string..**.**
29690 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e   ^If pzTail is n
296a0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a  ot NULL then *pz
296b0 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
296c0 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
296d0 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20  st byte.** past 
296e0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
296f0 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
29700 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
29710 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
29720 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  .** compile the 
29730 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20  first statement 
29740 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
29750 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
29760 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20  ting to.** what 
29770 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c  remains uncompil
29780 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74  ed..**.** ^*ppSt
29790 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
297a0 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
297b0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
297c0 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
297d0 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
297e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
297f0 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72  ep()].  ^If ther
29800 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
29810 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a  ppStmt is set.**
29820 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74   to NULL.  ^If t
29830 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
29840 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
29850 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
29860 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
29870 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
29880 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
29890 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
298a0 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
298b0 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
298c0 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
298d0 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
298e0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
298f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
29900 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
29910 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
29920 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53   with it..** ppS
29930 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e  tmt may not be N
29940 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73  ULL..**.** ^On s
29950 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69  uccess, the sqli
29960 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61  te3_prepare() fa
29970 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73  mily of routines
29980 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
29990 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73  OK];.** otherwis
299a0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
299b0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
299c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
299d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e  _prepare_v2() an
299e0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
299f0 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61  e16_v2() interfa
29a00 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d  ces are.** recom
29a10 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
29a20 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65  ew programs. The
29a30 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72   two older inter
29a40 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e  faces are retain
29a50 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61  ed.** for backwa
29a60 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
29a70 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
29a80 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
29a90 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22  .** ^In the "v2"
29aa0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
29ab0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29ac0 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
29ad0 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
29ae0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
29af0 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
29b00 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
29b10 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
29b20 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
29b30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
29b40 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
29b50 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
29b60 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
29b70 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
29b80 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
29b90 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
29ba0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
29bb0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
29bc0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
29bd0 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
29be0 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
29bf0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
29c00 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
29c10 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
29c20 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
29c30 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
29c40 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e   again..** </li>
29c50 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
29c60 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
29c70 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
29c80 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
29c90 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
29ca0 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
29cb0 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
29cc0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
29cd0 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
29ce0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
29cf0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
29d00 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
29d10 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
29d20 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
29d30 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
29d40 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
29d50 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
29d60 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
29d70 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29d80 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
29d90 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
29da0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
29db0 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
29dc0 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
29dd0 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
29de0 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
29df0 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
29e00 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
29e10 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
29e20 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
29e30 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
29e40 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  the specific val
29e50 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72  ue bound to [par
29e60 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61  ameter | host pa
29e70 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
29e80 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
29e90 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
29ea0 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71   the choice of q
29eb0 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20  uery plan for a 
29ec0 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68  statement,.** th
29ed0 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
29ee0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
29ef0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
29f00 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68  d, as if there h
29f10 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63  ad been .** a sc
29f20 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20  hema change, on 
29f30 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69  the first  [sqli
29f40 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
29f50 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63   following any c
29f60 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20  hange.** to the 
29f70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
29f80 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
29f90 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65  f that [paramete
29fa0 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65  r]. .** ^The spe
29fb0 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57  cific value of W
29fc0 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72  HERE-clause [par
29fd0 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e  ameter] might in
29fe0 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20  fluence the .** 
29ff0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2a000 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61  plan if the para
2a010 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66  meter is the lef
2a020 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61  t-hand side of a
2a030 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47   [LIKE].** or [G
2a040 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72  LOB] operator or
2a050 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2a060 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f  r is compared to
2a070 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75   an indexed colu
2a080 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53  mn.** and the [S
2a090 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
2a0a0 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  T3] compile-time
2a0b0 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
2a0c0 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c  ed..** the .** <
2a0d0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  /li>.** </ol>.*/
2a0e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2a0f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2a100 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2a110 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2a120 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2a130 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2a140 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2a150 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2a160 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2a170 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2a180 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2a190 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2a1a0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2a1b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2a1c0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2a1d0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2a1e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2a1f0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2a200 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2a210 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2a220 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53   of zSql */.);.S
2a230 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2a240 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2a250 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2a260 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2a270 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2a280 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2a290 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2a2a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2a2b0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
2a2c0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2a2d0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2a2e0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2a2f0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2a300 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2a310 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2a320 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2a330 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2a340 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
2a350 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2a360 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2a370 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2a380 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2a390 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a3a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2a3b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2a3c0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2a3d0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2a3e0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2a3f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2a400 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2a410 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2a420 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2a430 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2a440 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2a450 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2a460 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2a470 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2a480 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2a490 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2a4a0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2a4b0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2a4c0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2a4d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2a4e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2a4f0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
2a500 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2a510 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2a520 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2a530 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2a540 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2a550 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2a560 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2a570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2a580 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2a590 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2a5a0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2a5b0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2a5c0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2a5d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a5e0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2a5f0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2a600 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2a610 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2a620 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
2a630 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
2a640 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
2a650 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
2a660 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
2a670 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
2a680 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
2a690 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
2a6a0 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
2a6b0 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
2a6c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
2a6d0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
2a6e0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
2a6f0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
2a700 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a710 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2a720 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2a730 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2a740 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2a750 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
2a760 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2a770 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
2a780 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
2a790 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
2a7a0 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
2a7b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2a7c0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
2a7d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2a7e0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
2a7f0 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
2a800 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
2a810 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
2a820 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
2a830 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
2a840 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2a850 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
2a860 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2a870 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2a880 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2a890 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
2a8a0 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
2a8b0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
2a8c0 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
2a8d0 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
2a8e0 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
2a8f0 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
2a900 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
2a910 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
2a920 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
2a930 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
2a940 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
2a950 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
2a960 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
2a970 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2a980 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
2a990 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
2a9a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2a9b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
2a9c0 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
2a9d0 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
2a9e0 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
2a9f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
2aa00 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
2aa10 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2aa20 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
2aa30 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2aa40 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
2aa50 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
2aa60 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
2aa70 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
2aa80 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
2aa90 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
2aaa0 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
2aab0 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
2aac0 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
2aad0 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
2aae0 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
2aaf0 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
2ab00 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
2ab10 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
2ab20 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
2ab30 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
2ab40 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
2ab50 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
2ab60 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
2ab70 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
2ab80 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
2ab90 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
2aba0 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
2abb0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
2abc0 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
2abd0 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
2abe0 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
2abf0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
2ac00 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
2ac10 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
2ac20 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
2ac30 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
2ac40 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
2ac50 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
2ac60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
2ac70 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
2ac80 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
2ac90 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2aca0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
2acb0 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49  on disk..*/.SQLI
2acc0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2acd0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2ace0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2acf0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2ad00 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
2ad10 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
2ad20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
2ad30 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  en Reset.**.** ^
2ad40 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2ad50 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61  _busy(S) interfa
2ad60 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2ad70 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68  (non-zero) if th
2ad80 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2ad90 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20  tatement] S has 
2ada0 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20  been stepped at 
2adb0 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67  least once using
2adc0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
2add0 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e  ep(S)] but has n
2ade0 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  ot run to comple
2adf0 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20  tion and/or has 
2ae00 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73  not .** been res
2ae10 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  et using [sqlite
2ae20 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54  3_reset(S)].  ^T
2ae30 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2ae40 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72  busy(S).** inter
2ae50 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c  face returns fal
2ae60 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c  se if S is a NUL
2ae70 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53  L pointer.  If S
2ae80 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55   is not a .** NU
2ae90 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69  LL pointer and i
2aea0 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20  s not a pointer 
2aeb0 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70  to a valid [prep
2aec0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2aed0 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20  ** object, then 
2aee0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2aef0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
2af00 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
2af10 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  le..**.** This i
2af20 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
2af30 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74  used in combinat
2af40 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  ion [sqlite3_nex
2af50 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20  t_stmt()].** to 
2af60 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61  locate all prepa
2af70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61  red statements a
2af80 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
2af90 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f   database .** co
2afa0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72  nnection that ar
2afb0 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69  e in need of bei
2afc0 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20  ng reset.  This 
2afd0 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20  can be used,.** 
2afe0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  for example, in 
2aff0 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69  diagnostic routi
2b000 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f  nes to search fo
2b010 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73  r prepared .** s
2b020 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61  tatements that a
2b030 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61  re holding a tra
2b040 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a  nsaction open..*
2b050 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2b060 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2b070 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
2b080 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b090 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
2b0a0 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
2b0b0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
2b0c0 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
2b0d0 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
2b0e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b0f0 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
2b100 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
2b110 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2b120 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
2b130 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
2b140 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
2b150 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
2b160 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
2b170 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
2b180 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
2b190 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
2b1a0 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
2b1b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2b1c0 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
2b1d0 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
2b1e0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
2b1f0 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
2b200 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
2b210 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
2b220 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
2b230 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
2b240 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
2b250 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
2b260 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
2b270 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b280 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
2b290 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
2b2a0 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
2b2b0 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
2b2c0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2b2d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
2b2e0 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
2b2f0 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
2b300 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
2b310 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
2b320 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
2b330 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
2b340 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b350 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
2b360 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
2b370 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
2b380 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
2b390 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
2b3a0 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
2b3b0 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20  d.  An internal 
2b3c0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
2b3d0 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
2b3e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2b3f0 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
2b400 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
2b410 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
2b420 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2b430 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
2b440 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
2b450 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
2b460 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
2b470 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
2b480 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
2b490 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2b4a0 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
2b4b0 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
2b4c0 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
2b4d0 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
2b4e0 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
2b4f0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
2b500 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
2b510 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
2b520 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
2b530 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
2b540 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
2b550 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
2b560 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2b570 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2b580 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
2b590 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
2b5a0 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
2b5b0 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
2b5c0 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
2b5d0 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
2b5e0 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
2b5f0 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
2b600 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
2b610 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
2b620 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
2b630 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2b640 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
2b650 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
2b660 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
2b670 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b680 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
2b690 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
2b6a0 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
2b6b0 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
2b6c0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
2b6d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2b6e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
2b6f0 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
2b700 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
2b710 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
2b720 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2b730 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2b740 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
2b750 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
2b760 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2b770 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
2b780 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
2b790 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2b7a0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
2b7b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2b7c0 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
2b7d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2b7e0 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
2b7f0 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
2b800 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
2b810 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
2b820 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2b830 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
2b840 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
2b850 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
2b860 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b870 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
2b880 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
2b890 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
2b8a0 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
2b8b0 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
2b8c0 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
2b8d0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
2b8e0 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
2b8f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
2b900 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
2b910 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
2b920 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2b930 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
2b940 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2b950 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
2b960 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2b970 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2b980 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2b990 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
2b9a0 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
2b9b0 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
2b9c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2b9d0 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
2b9e0 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
2b9f0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2ba00 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
2ba10 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
2ba20 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
2ba30 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2ba40 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
2ba50 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
2ba60 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
2ba70 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
2ba80 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2ba90 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
2baa0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
2bab0 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
2bac0 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
2bad0 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
2bae0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
2baf0 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
2bb00 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
2bb10 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
2bb20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
2bb30 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
2bb40 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
2bb50 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
2bb60 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
2bb70 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  }.**.** ^(In the
2bb80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
2bb90 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
2bba0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2bbb0 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
2bbc0 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
2bbd0 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
2bbe0 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
2bbf0 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
2bc00 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
2bc10 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
2bc20 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2bc30 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
2bc40 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
2bc50 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
2bc60 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
2bc70 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
2bc80 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
2bc90 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
2bca0 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
2bcb0 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
2bcc0 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
2bcd0 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
2bce0 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
2bcf0 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
2bd00 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
2bd10 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
2bd20 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2bd30 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
2bd40 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
2bd50 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
2bd60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2bd70 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
2bd80 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
2bd90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2bda0 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
2bdb0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2bdc0 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
2bdd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2bde0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
2bdf0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2be00 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
2be10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2be20 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
2be30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2be40 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2be50 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
2be60 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
2be70 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
2be80 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
2be90 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2bea0 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
2beb0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
2bec0 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
2bed0 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
2bee0 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
2bef0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
2bf00 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
2bf10 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
2bf20 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
2bf30 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
2bf40 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
2bf50 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
2bf60 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
2bf70 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
2bf80 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2bf90 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
2bfa0 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
2bfb0 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
2bfc0 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
2bfd0 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
2bfe0 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
2bff0 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
2c000 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
2c010 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
2c020 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
2c030 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
2c040 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2c050 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
2c060 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
2c070 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2c080 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
2c090 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
2c0a0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ameter..**.** ^(
2c0b0 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
2c0c0 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
2c0d0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
2c0e0 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
2c0f0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
2c100 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
2c110 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
2c120 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
2c130 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2c140 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
2c150 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
2c160 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2c170 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
2c180 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2c190 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2c1a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2c1b0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2c1c0 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65  ext16().** is ne
2c1d0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
2c1e0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
2c1f0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
2c200 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2c210 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
2c220 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2c230 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
2c240 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2c250 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2c260 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  () is negative, 
2c270 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61  then.** the beha
2c280 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2c290 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  d..** If a non-n
2c2a0 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
2c2b0 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
2c2c0 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
2c2d0 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
2c2e0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2c2f0 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61  ext16() then tha
2c300 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
2c310 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
2c320 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65  set.** where the
2c330 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
2c340 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75  would occur assu
2c350 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20  ming the string 
2c360 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d  were NUL.** term
2c370 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
2c380 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
2c390 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66  ccur at byte off
2c3a0 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a  sets less than .
2c3b0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ** the value of 
2c3c0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2c3d0 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65  eter then the re
2c3e0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76  sulting string v
2c3f0 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  alue will.** con
2c400 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
2c410 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  Ls.  The result 
2c420 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  of expressions i
2c430 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73  nvolving strings
2c440 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65  .** with embedde
2c450 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
2c460 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2c470 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
2c480 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
2c490 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
2c4a0 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
2c4b0 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
2c4c0 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
2c4d0 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
2c4e0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2c4f0 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
2c500 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
2c510 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
2c520 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72   it.  ^The destr
2c530 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a  uctor is called.
2c540 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ** to dispose of
2c550 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
2c560 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
2c570 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
2c580 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20  bind_blob(),.** 
2c590 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2c5a0 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  t(), or sqlite3_
2c5b0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61  bind_text16() fa
2c5c0 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68  ils.  .** ^If th
2c5d0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2c5e0 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
2c5f0 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
2c600 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
2c610 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
2c620 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
2c630 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
2c640 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
2c650 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
2c660 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
2c670 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
2c680 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
2c690 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
2c6a0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
2c6b0 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
2c6c0 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
2c6d0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2c6e0 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
2c6f0 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
2c700 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2c710 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2c720 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2c730 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2c740 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
2c750 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
2c760 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
2c770 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
2c780 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
2c790 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
2c7a0 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
2c7b0 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
2c7c0 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
2c7d0 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
2c7e0 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
2c7f0 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
2c800 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
2c810 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
2c820 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
2c830 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
2c840 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
2c850 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
2c860 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
2c870 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
2c880 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
2c890 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
2c8a0 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
2c8b0 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
2c8c0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
2c8d0 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  LOB..**.** ^If a
2c8e0 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
2c8f0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2c900 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
2c910 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
2c920 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
2c930 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c940 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
2c950 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2c960 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
2c970 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2c980 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
2c990 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
2c9a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c9b0 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
2c9c0 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
2c9d0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2c9e0 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
2c9f0 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
2ca00 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
2ca10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ca20 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
2ca30 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
2ca40 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
2ca50 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
2ca60 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
2ca70 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
2ca80 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
2ca90 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
2caa0 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
2cab0 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
2cac0 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
2cad0 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
2cae0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2caf0 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
2cb00 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
2cb10 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
2cb20 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
2cb30 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
2cb40 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
2cb50 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
2cb60 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
2cb70 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2cb80 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
2cb90 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
2cba0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
2cbb0 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
2cbc0 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
2cbd0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2cbe0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2cbf0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
2cc00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2cc10 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2cc20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2cc30 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2cc40 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
2cc50 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2cc60 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
2cc70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2cc80 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
2cc90 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
2cca0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
2ccb0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2ccc0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2ccd0 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
2cce0 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  e);.SQLITE_API i
2ccf0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2cd00 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2cd10 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51  *, int, int);.SQ
2cd20 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2cd30 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
2cd40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2cd50 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
2cd60 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  4);.SQLITE_API i
2cd70 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2cd80 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
2cd90 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  t*, int);.SQLITE
2cda0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2cdb0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
2cdc0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2cdd0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
2cde0 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
2cdf0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
2ce00 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2ce10 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2ce20 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2ce30 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2ce40 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
2ce50 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2ce60 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2ce70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ce80 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
2ce90 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2cea0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2ceb0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
2cec0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ced0 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
2cee0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2cef0 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
2cf00 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  eters.**.** ^Thi
2cf10 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
2cf20 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
2cf30 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
2cf40 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
2cf50 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
2cf60 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
2cf70 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
2cf80 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
2cf90 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
2cfa0 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
2cfb0 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
2cfc0 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
2cfd0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
2cfe0 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
2cff0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2d000 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
2d010 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
2d020 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
2d030 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
2d040 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
2d050 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
2d060 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
2d070 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
2d080 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
2d090 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
2d0a0 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
2d0b0 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
2d0c0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
2d0d0 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
2d0e0 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
2d0f0 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
2d100 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
2d110 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
2d120 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
2d130 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2d140 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2d150 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2d160 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2d170 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2d180 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
2d190 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2d1a0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2d1b0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2d1c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2d1d0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
2d1e0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2d1f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2d200 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
2d210 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
2d220 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2d230 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
2d240 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
2d250 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
2d260 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
2d270 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
2d280 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2d290 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2d2a0 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
2d2b0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
2d2c0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2d2d0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2d2e0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
2d2f0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
2d300 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
2d310 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2d320 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
2d330 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
2d340 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2d350 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
2d360 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
2d370 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
2d380 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
2d390 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
2d3a0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2d3b0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
2d3c0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
2d3d0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
2d3e0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
2d3f0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
2d400 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
2d410 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
2d420 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2d430 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
2d440 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2d450 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
2d460 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
2d470 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2d480 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
2d490 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
2d4a0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
2d4b0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
2d4c0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2d4d0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
2d4e0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
2d4f0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
2d500 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
2d510 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
2d520 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
2d530 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
2d540 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2d550 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2d560 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2d570 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2d580 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2d590 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2d5a0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2d5b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2d5c0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2d5d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2d5e0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2d5f0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
2d600 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2d610 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2d620 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
2d630 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
2d640 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
2d650 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
2d660 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
2d670 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   Name.**.** ^Ret
2d680 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
2d690 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
2d6a0 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
2d6b0 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
2d6c0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2d6d0 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
2d6e0 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
2d6f0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
2d700 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
2d710 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2d720 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
2d730 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
2d740 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
2d750 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
2d760 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
2d770 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
2d780 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
2d790 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
2d7a0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
2d7b0 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
2d7c0 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
2d7d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
2d7e0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
2d7f0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2d800 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2d810 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2d820 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2d830 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2d840 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
2d850 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2d860 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2d870 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2d880 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2d890 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2d8a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d8b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2d8c0 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
2d8d0 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
2d8e0 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
2d8f0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
2d900 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
2d910 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
2d920 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
2d930 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
2d940 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
2d950 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2d960 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
2d970 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2d980 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2d990 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
2d9a0 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
2d9b0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
2d9c0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45   NULL..*/.SQLITE
2d9d0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2d9e0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2d9f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2da00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2da10 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
2da20 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
2da30 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  et.**.** ^Return
2da40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2da50 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
2da60 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
2da70 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
2da80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2da90 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
2daa0 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
2dab0 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
2dac0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
2dad0 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
2dae0 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
2daf0 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
2db00 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2db10 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2db20 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
2db30 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2db40 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
2db50 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2db60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2db70 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
2db80 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2db90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2dba0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2dbb0 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
2dbc0 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
2dbd0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
2dbe0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
2dbf0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2dc00 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
2dc10 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2dc20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2dc30 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2dc40 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2dc50 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
2dc60 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
2dc70 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2dc80 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2dc90 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2dca0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
2dcb0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2dcc0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2dcd0 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
2dce0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
2dcf0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2dd00 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2dd10 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
2dd20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2dd30 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
2dd40 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
2dd50 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
2dd60 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
2dd70 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2dd80 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
2dd90 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
2dda0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2ddb0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
2ddc0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
2ddd0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2dde0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2ddf0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2de00 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2de10 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2de20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2de30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2de40 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2de50 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2de60 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
2de70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2de80 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
2de90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2dea0 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
2deb0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2dec0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
2ded0 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
2dee0 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
2def0 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
2df00 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
2df10 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
2df20 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
2df30 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
2df40 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
2df50 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2df60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
2df70 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
2df80 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
2df90 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
2dfa0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
2dfb0 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
2dfc0 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
2dfd0 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
2dfe0 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
2dff0 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
2e000 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
2e010 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
2e020 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
2e030 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
2e040 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
2e050 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
2e060 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2e070 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2e080 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e090 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
2e0a0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2e0b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2e0c0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2e0d0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
2e0e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
2e0f0 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
2e100 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2e110 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2e120 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
2e130 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
2e140 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
2e150 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
2e160 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
2e170 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
2e180 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
2e190 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
2e1a0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2e1b0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
2e1c0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2e1d0 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
2e1e0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
2e1f0 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
2e200 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
2e210 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2e220 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
2e230 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
2e240 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
2e250 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
2e260 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2e270 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
2e280 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
2e290 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2e2a0 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
2e2b0 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
2e2c0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
2e2d0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
2e2e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e2f0 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
2e300 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2e310 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2e320 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2e330 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2e340 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2e350 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2e360 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2e370 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2e380 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2e390 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
2e3a0 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
2e3b0 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
2e3c0 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
2e3d0 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
2e3e0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
2e3f0 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
2e400 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
2e410 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
2e420 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
2e430 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
2e440 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2e450 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2e460 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
2e470 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2e480 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
2e490 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2e4a0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2e4b0 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
2e4c0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
2e4d0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
2e4e0 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
2e4f0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
2e500 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
2e510 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
2e520 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
2e530 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
2e540 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
2e550 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
2e560 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
2e570 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
2e580 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
2e590 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
2e5a0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
2e5b0 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
2e5c0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
2e5d0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
2e5e0 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
2e5f0 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
2e600 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
2e610 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2e620 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
2e630 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
2e640 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
2e650 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2e660 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2e670 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
2e680 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
2e690 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
2e6a0 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
2e6b0 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
2e6c0 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
2e6d0 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
2e6e0 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
2e6f0 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
2e700 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
2e710 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
2e720 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
2e730 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
2e740 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
2e750 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
2e760 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
2e770 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
2e780 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
2e790 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
2e7a0 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
2e7b0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
2e7c0 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
2e7d0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2e7e0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2e7f0 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
2e800 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
2e810 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
2e820 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
2e830 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
2e840 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
2e850 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
2e860 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2e870 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2e880 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2e890 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
2e8a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2e8b0 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
2e8c0 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
2e8d0 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
2e8e0 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
2e8f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
2e900 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
2e910 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
2e920 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2e930 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2e940 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
2e950 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2e960 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2e970 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
2e980 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2e990 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2e9a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2e9b0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2e9c0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2e9d0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2e9e0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
2e9f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2ea00 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
2ea10 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2ea20 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2ea30 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2ea40 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
2ea50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2ea60 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2ea70 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2ea80 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
2ea90 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2eaa0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2eab0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2eac0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ead0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
2eae0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2eaf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2eb00 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
2eb10 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
2eb20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  Result.**.** ^(T
2eb30 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2eb40 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
2eb50 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2eb60 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
2eb70 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
2eb80 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2eb90 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2eba0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
2ebb0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
2ebc0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
2ebd0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
2ebe0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
2ebf0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2ec00 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
2ec10 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
2ec20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
2ec30 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
2ec40 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
2ec50 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2ec60 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
2ec70 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2ec80 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
2ec90 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2eca0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
2ecb0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2ecc0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
2ecd0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
2ece0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
2ecf0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2ed00 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
2ed10 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
2ed20 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
2ed30 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
2ed40 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
2ed50 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
2ed60 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
2ed70 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
2ed80 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
2ed90 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
2eda0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
2edb0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
2edc0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
2edd0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
2ede0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
2edf0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
2ee00 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
2ee10 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2ee20 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
2ee30 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
2ee40 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
2ee50 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
2ee60 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
2ee70 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
2ee80 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
2ee90 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
2eea0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
2eeb0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
2eec0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
2eed0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
2eee0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
2eef0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
2ef00 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
2ef10 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
2ef20 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
2ef30 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
2ef40 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
2ef50 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
2ef60 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
2ef70 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
2ef80 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2ef90 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2efa0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2efb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2efc0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2efd0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2efe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2eff0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
2f000 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2f010 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
2f020 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
2f030 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
2f040 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2f050 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
2f060 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2f070 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2f080 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2f090 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2f0a0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2f0b0 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
2f0c0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
2f0d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2f0e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2f0f0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
2f100 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
2f110 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
2f120 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
2f130 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
2f140 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
2f150 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
2f160 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2f170 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2f180 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
2f190 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
2f1a0 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
2f1b0 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
2f1c0 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
2f1d0 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
2f1e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2f1f0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2f200 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2f210 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
2f220 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2f230 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
2f240 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2f250 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2f260 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
2f270 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
2f280 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2f290 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
2f2a0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
2f2b0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2f2c0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
2f2d0 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
2f2e0 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
2f2f0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2f300 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
2f310 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
2f320 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
2f330 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
2f340 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
2f350 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
2f360 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
2f370 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
2f380 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2f390 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
2f3a0 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
2f3b0 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
2f3c0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2f3d0 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
2f3e0 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
2f3f0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2f400 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
2f410 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2f420 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
2f430 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
2f440 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
2f450 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
2f460 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
2f470 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2f480 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
2f490 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
2f4a0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
2f4b0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
2f4c0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
2f4d0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
2f4e0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
2f4f0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
2f500 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
2f510 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
2f520 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2f530 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
2f540 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
2f550 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
2f560 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
2f570 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
2f580 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
2f590 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2f5a0 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
2f5b0 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
2f5c0 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
2f5d0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2f5e0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2f5f0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
2f600 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
2f610 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
2f620 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2f630 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2f640 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2f650 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
2f660 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
2f670 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
2f680 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
2f690 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
2f6a0 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
2f6b0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
2f6c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
2f6d0 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
2f6e0 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
2f6f0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
2f700 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
2f710 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
2f720 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
2f730 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
2f740 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2f750 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
2f760 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
2f770 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
2f780 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
2f790 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
2f7a0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
2f7b0 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
2f7c0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
2f7d0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
2f7e0 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
2f7f0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
2f800 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2f810 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2f820 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
2f830 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
2f840 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
2f850 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2f860 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
2f870 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
2f880 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2f890 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
2f8a0 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
2f8b0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
2f8c0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
2f8d0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
2f8e0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
2f8f0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
2f900 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
2f910 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
2f920 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2f930 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
2f940 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2f950 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
2f960 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
2f970 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2f980 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
2f990 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
2f9a0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2f9b0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
2f9c0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
2f9d0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
2f9e0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
2f9f0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
2fa00 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
2fa10 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
2fa20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fa30 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
2fa40 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
2fa50 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
2fa60 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
2fa70 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
2fa80 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
2fa90 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
2faa0 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
2fab0 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
2fac0 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
2fad0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
2fae0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2faf0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
2fb00 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
2fb10 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
2fb20 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
2fb30 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
2fb40 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
2fb50 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
2fb60 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
2fb70 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
2fb80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2fb90 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
2fba0 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2fbb0 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
2fbc0 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
2fbd0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2fbe0 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
2fbf0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2fc00 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
2fc10 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
2fc20 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
2fc30 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2fc40 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
2fc50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2fc60 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
2fc70 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
2fc80 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
2fc90 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2fca0 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
2fcb0 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
2fcc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
2fcd0 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
2fce0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2fcf0 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
2fd00 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
2fd10 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
2fd20 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
2fd30 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2fd40 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
2fd50 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
2fd60 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
2fd70 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
2fd80 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
2fd90 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
2fda0 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
2fdb0 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
2fdc0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
2fdd0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2fde0 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
2fdf0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
2fe00 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
2fe10 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
2fe20 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
2fe30 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
2fe40 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
2fe50 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
2fe60 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
2fe70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
2fe80 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
2fe90 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
2fea0 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
2feb0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
2fec0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
2fed0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2fee0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
2fef0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2ff00 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
2ff10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ff20 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2ff30 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
2ff40 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
2ff50 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
2ff60 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2ff70 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
2ff80 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
2ff90 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
2ffa0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
2ffb0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
2ffc0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
2ffd0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
2ffe0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2fff0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
30000 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
30010 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
30020 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
30030 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
30040 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
30050 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
30060 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
30070 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
30080 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
30090 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
300a0 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
300b0 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
300c0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
300d0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
300e0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
300f0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
30100 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
30110 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
30120 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
30130 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ended..*/.SQLITE
30140 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
30150 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
30160 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
30170 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
30180 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
30190 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult set.**.** ^
301a0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
301b0 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
301c0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
301d0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
301e0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
301f0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
30200 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
30210 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30220 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
30230 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
30240 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
30250 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
30260 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
30270 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
30280 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
30290 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
302a0 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
302b0 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
302c0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
302d0 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
302e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
302f0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
30300 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
30310 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
30320 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
30330 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
30340 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
30350 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
30360 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
30370 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
30380 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
30390 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
303a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
303b0 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
303c0 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
303d0 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
303e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
303f0 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
30400 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
30410 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
30420 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
30430 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
30440 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
30450 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
30460 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
30470 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
30480 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
30490 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
304a0 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
304b0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
304c0 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
304d0 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51  n_count()].*/.SQ
304e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
304f0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
30500 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
30510 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
30520 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
30530 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
30540 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
30550 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
30560 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
30570 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
30580 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
30590 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
305a0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
305b0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
305c0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
305d0 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
305e0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
305f0 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
30600 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
30610 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
30620 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
30630 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
30640 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
30650 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
30660 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
30670 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
30680 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
30690 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
306a0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
306b0 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
306c0 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
306d0 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
306e0 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
306f0 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
30700 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
30710 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
30720 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
30730 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
30740 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
30750 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
30760 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
30770 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
30780 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
30790 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
307a0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
307b0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
307c0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
307d0 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
307e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
307f0 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
30800 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
30810 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
30820 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
30830 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
30840 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
30850 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
30860 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
30870 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
30880 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
30890 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
308a0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
308b0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
308c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
308d0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
308e0 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
308f0 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
30900 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
30910 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
30920 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
30930 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
30940 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
30950 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
30960 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
30970 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
30980 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
30990 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
309a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
309b0 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
309c0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
309d0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
309e0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
309f0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
30a00 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
30a10 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
30a20 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
30a30 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
30a40 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
30a50 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
30a60 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
30a70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
30a80 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
30a90 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
30aa0 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
30ab0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
30ac0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
30ad0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
30ae0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
30af0 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
30b00 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
30b10 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
30b20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
30b30 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
30b40 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
30b50 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
30b60 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
30b70 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
30b80 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
30b90 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
30ba0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
30bb0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
30bc0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
30bd0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
30be0 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
30bf0 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
30c00 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
30c10 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
30c20 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
30c30 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
30c40 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
30c50 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
30c60 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
30c70 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
30c80 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
30c90 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
30ca0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
30cb0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
30cc0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
30cd0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
30ce0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
30cf0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
30d00 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
30d10 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
30d20 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
30d30 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
30d40 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
30d50 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
30d60 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
30d70 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
30d80 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
30d90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30da0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
30db0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
30dc0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
30dd0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
30de0 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
30df0 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
30e00 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
30e10 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
30e20 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
30e30 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
30e40 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
30e50 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
30e60 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
30e70 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
30e80 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
30e90 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
30ea0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
30eb0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
30ec0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
30ed0 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
30ee0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
30ef0 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
30f00 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
30f10 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
30f20 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
30f30 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
30f40 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
30f50 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
30f60 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
30f70 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
30f80 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
30f90 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
30fa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30fb0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
30fc0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
30fd0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
30fe0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
30ff0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
31000 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
31010 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31020 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
31030 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
31040 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
31050 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
31060 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
31070 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
31080 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
31090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
310a0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
310b0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
310c0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
310d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
310e0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
310f0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
31100 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
31110 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
31120 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
31130 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
31140 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
31150 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
31160 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
31170 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
31180 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
31190 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
311a0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
311b0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
311c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
311d0 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
311e0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
311f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
31200 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
31210 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
31220 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
31230 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
31240 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
31250 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
31260 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
31270 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
31280 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
31290 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
312a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
312b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
312c0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
312d0 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
312e0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
312f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
31300 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
31310 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
31320 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
31330 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31340 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
31350 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
31360 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
31370 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
31380 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
31390 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
313a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
313b0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
313c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
313d0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
313e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
313f0 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
31400 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
31410 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
31420 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
31430 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
31440 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
31450 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
31460 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
31470 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
31480 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
31490 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
314a0 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
314b0 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
314c0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
314d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
314e0 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
314f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
31500 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
31510 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
31520 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
31530 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
31540 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
31550 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
31560 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
31570 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
31580 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31590 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
315a0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
315b0 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
315c0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
315d0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
315e0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
315f0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
31600 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
31610 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
31620 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
31630 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
31640 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
31650 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
31660 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
31670 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
31680 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
31690 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
316a0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
316b0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
316c0 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
316d0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
316e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
316f0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
31700 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
31710 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
31720 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
31730 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
31740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
31750 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
31760 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
31770 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
31780 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
31790 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
317a0 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
317b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
317c0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
317d0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
317e0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
317f0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
31800 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
31810 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
31820 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
31830 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
31840 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
31850 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
31860 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
31870 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
31880 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
31890 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
318a0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
318b0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
318c0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
318d0 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
318e0 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
318f0 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
31900 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
31910 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
31920 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
31930 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
31940 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
31950 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
31960 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
31970 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
31980 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
31990 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
319a0 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
319b0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
319c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
319d0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
319e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
319f0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
31a00 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
31a10 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
31a20 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
31a30 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
31a40 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
31a50 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
31a60 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
31a70 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
31a80 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
31a90 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
31aa0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
31ab0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
31ac0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
31ad0 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
31ae0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
31af0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
31b00 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
31b10 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
31b20 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
31b30 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
31b40 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
31b50 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
31b60 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
31b70 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
31b80 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
31b90 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
31ba0 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
31bb0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
31bc0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
31bd0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
31be0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
31bf0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
31c00 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
31c10 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
31c20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
31c30 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
31c40 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
31c50 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
31c60 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
31c70 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
31c80 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
31c90 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
31ca0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
31cb0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
31cc0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
31cd0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
31ce0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
31cf0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
31d00 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
31d10 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
31d20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
31d30 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
31d40 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
31d50 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
31d60 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
31d70 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
31d80 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
31d90 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
31da0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
31db0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
31dc0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
31dd0 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
31de0 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
31df0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
31e00 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
31e10 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
31e20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
31e30 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
31e40 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
31e50 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
31e60 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
31e70 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
31e80 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
31e90 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
31ea0 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
31eb0 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
31ec0 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
31ed0 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
31ee0 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
31ef0 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
31f00 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
31f10 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
31f20 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
31f30 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
31f40 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
31f50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
31f60 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
31f70 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
31f80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
31f90 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
31fa0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
31fb0 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
31fc0 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
31fd0 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
31fe0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
31ff0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
32000 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
32010 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
32020 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
32030 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
32040 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
32050 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
32060 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
32070 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
32080 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
32090 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
320a0 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
320b0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
320c0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
320d0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
320e0 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
320f0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
32100 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
32110 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
32120 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
32130 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
32140 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
32150 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
32160 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
32170 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
32180 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
32190 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
321a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
321b0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
321c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
321d0 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
321e0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
321f0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
32200 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
32210 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
32220 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
32230 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
32240 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
32250 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
32260 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
32270 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
32280 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
32290 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
322a0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
322b0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
322c0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
322d0 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
322e0 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
322f0 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
32300 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
32310 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
32320 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
32330 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
32340 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
32350 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
32360 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
32370 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
32380 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
32390 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
323a0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
323b0 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
323c0 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
323d0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
323e0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
323f0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
32400 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
32410 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
32420 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
32430 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
32440 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32450 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
32460 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
32470 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
32480 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
32490 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
324a0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
324b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
324c0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
324d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
324e0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
324f0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
32500 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
32510 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
32520 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
32530 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
32540 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
32550 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32560 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
32570 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
32580 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
32590 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
325a0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
325b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
325c0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
325d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
325e0 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
325f0 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
32600 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
32610 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
32620 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
32630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
32640 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
32650 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
32660 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
32670 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
32680 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
32690 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
326a0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
326b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
326c0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
326d0 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
326e0 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
326f0 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
32700 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
32710 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
32720 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
32730 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
32740 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
32750 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
32760 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
32770 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
32780 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
32790 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
327a0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
327b0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
327c0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
327d0 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
327e0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
327f0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
32800 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
32810 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
32820 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
32830 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
32840 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
32850 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
32860 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
32870 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
32880 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
32890 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
328a0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
328b0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
328c0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
328d0 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
328e0 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
328f0 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
32900 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
32910 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
32920 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
32930 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
32940 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
32950 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
32960 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
32970 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
32980 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
32990 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
329a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
329b0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
329c0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
329d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
329e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
329f0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
32a00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
32a10 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
32a20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
32a30 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
32a40 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
32a50 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
32a60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
32a70 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
32a80 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
32a90 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
32aa0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
32ab0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
32ac0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
32ad0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
32ae0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
32af0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
32b00 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73  TE_API const uns
32b10 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
32b20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
32b30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
32b40 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
32b50 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
32b60 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
32b70 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
32b80 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
32b90 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
32ba0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32bb0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
32bc0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
32bd0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
32be0 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
32bf0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
32c00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
32c10 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
32c20 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
32c30 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
32c40 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
32c50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
32c60 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
32c70 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
32c80 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
32c90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
32ca0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
32cb0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
32cc0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
32cd0 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
32ce0 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
32cf0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
32d00 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
32d10 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
32d20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
32d30 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
32d40 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
32d50 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
32d60 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
32d70 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
32d80 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
32d90 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
32da0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
32db0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
32dc0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
32dd0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
32de0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
32df0 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
32e00 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
32e10 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
32e20 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
32e30 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
32e40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
32e50 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
32e60 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
32e70 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
32e80 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
32e90 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
32ea0 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
32eb0 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
32ec0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
32ed0 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
32ee0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
32ef0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
32f00 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
32f10 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
32f20 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
32f30 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
32f40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
32f50 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
32f60 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
32f70 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
32f80 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
32f90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32fa0 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
32fb0 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
32fc0 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
32fd0 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
32fe0 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
32ff0 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
33000 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
33010 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
33020 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
33030 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
33040 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
33050 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
33060 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
33070 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
33080 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
33090 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
330a0 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
330b0 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
330c0 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
330d0 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
330e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e   int sqlite3_fin
330f0 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
33100 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
33110 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
33120 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
33130 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
33140 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
33150 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
33160 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
33170 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
33180 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
33190 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
331a0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
331b0 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
331c0 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
331d0 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
331e0 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
331f0 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
33200 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
33210 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
33220 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
33230 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
33240 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
33250 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
33260 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
33270 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
33280 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
33290 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
332a0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
332b0 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
332c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
332d0 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
332e0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
332f0 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
33300 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
33310 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
33320 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
33330 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
33340 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33350 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
33360 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
33370 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
33380 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
33390 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
333a0 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
333b0 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
333c0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
333d0 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
333e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
333f0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
33400 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
33410 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
33420 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
33430 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33440 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
33450 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
33460 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
33470 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
33480 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
33490 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
334a0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
334b0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
334c0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
334d0 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
334e0 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
334f0 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
33500 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
33510 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
33520 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
33530 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
33540 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
33550 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
33560 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
33570 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
33580 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
33590 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
335a0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
335b0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
335c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
335d0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
335e0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
335f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33600 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
33610 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  s}.**.** ^These 
33620 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
33630 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
33640 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
33650 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
33660 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
33670 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
33680 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
33690 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
336a0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
336b0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
336c0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
336d0 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
336e0 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
336f0 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
33700 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
33710 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
33720 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
33730 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
33740 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
33750 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
33760 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
33770 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
33780 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
33790 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
337a0 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
337b0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
337c0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
337d0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
337e0 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
337f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
33800 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
33810 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
33820 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
33830 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
33840 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
33850 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
33860 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
33870 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33880 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
33890 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
338a0 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
338b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
338c0 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
338d0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
338e0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
338f0 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
33900 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
33910 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
33920 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
33930 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
33940 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
33950 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
33960 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
33970 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
33980 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
33990 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
339a0 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
339b0 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
339c0 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
339d0 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
339e0 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
339f0 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
33a00 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
33a10 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
33a20 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
33a30 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
33a40 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
33a50 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
33a60 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
33a70 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
33a80 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
33a90 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
33aa0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
33ab0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
33ac0 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
33ad0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
33ae0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
33af0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
33b00 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
33b10 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
33b20 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
33b30 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
33b40 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
33b50 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
33b60 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
33b70 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
33b80 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
33b90 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
33ba0 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
33bb0 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
33bc0 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
33bd0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
33be0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
33bf0 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
33c00 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
33c10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
33c20 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
33c30 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
33c40 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
33c50 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
33c60 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75  s.  Every SQL fu
33c70 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
33c80 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62  ation must be ab
33c90 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  le to work.** wi
33ca0 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  th UTF-8, UTF-16
33cb0 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e  le, or UTF-16be.
33cc0 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65    But some imple
33cd0 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  mentations may b
33ce0 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69  e.** more effici
33cf0 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63  ent with one enc
33d00 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68  oding than anoth
33d10 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61  er.  ^An applica
33d20 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f  tion may.** invo
33d30 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
33d40 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20  e_function() or 
33d50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33d60 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74  unction16() mult
33d70 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69  iple.** times wi
33d80 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  th the same func
33d90 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69  tion but with di
33da0 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f  fferent values o
33db0 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e  f eTextRep..** ^
33dc0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
33dd0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
33de0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
33df0 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
33e00 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
33e10 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
33e20 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
33e30 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
33e40 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
33e50 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
33e60 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
33e70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
33e80 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
33e90 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
33ea0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
33eb0 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
33ec0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
33ed0 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
33ee0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66  .**.** ^(The fif
33ef0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
33f00 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
33f10 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
33f20 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
33f30 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
33f40 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
33f50 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
33f60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
33f70 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  _data()].)^.**.*
33f80 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65  * ^The sixth, se
33f90 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68  venth and eighth
33fa0 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
33fb0 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
33fc0 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
33fd0 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
33fe0 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
33ff0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
34000 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
34010 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e  .** aggregate. ^
34020 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
34030 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
34040 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
34050 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
34060 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20   callback only; 
34070 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75  NULL pointers mu
34080 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
34090 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
340a0 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
340b0 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74  rs. ^An aggregat
340c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
340d0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
340e0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
340f0 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
34100 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   and NULL pointe
34110 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  r must be passed
34120 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
34130 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
34140 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
34150 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
34160 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74   pass NULL point
34170 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ers for all thre
34180 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  e function.** ca
34190 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e  llbacks..**.** ^
341a0 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61  (If the ninth pa
341b0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
341c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
341d0 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e  on_v2() is not N
341e0 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  ULL,.** then it 
341f0 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f  is destructor fo
34200 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
34210 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  n data pointer. 
34220 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74  .** The destruct
34230 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  or is invoked wh
34240 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
34250 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68  is deleted, eith
34260 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f  er by being.** o
34270 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65  verloaded or whe
34280 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
34290 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
342a0 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74  .)^.** ^The dest
342b0 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69  ructor is also i
342c0 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
342d0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
342e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
342f0 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  _v2() fails..** 
34300 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75  ^When the destru
34310 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ctor callback of
34320 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d   the tenth param
34330 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c  eter is invoked,
34340 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64   it.** is passed
34350 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
34360 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f  nt which is a co
34370 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  py of the applic
34380 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70  ation data .** p
34390 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
343a0 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   the fifth param
343b0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
343c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
343d0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  v2()..**.** ^It 
343e0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
343f0 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
34400 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
34410 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
34420 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
34430 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
34440 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
34450 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
34460 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
34470 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
34480 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
34490 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
344a0 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
344b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
344c0 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
344d0 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
344e0 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
344f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
34500 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
34510 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
34520 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
34530 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
34540 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
34550 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
34560 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
34570 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
34580 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
34590 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
345a0 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
345b0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
345c0 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
345d0 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
345e0 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
345f0 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
34600 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
34610 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
34620 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
34630 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
34640 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
34650 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
34660 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
34670 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
34680 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
34690 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
346a0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
346b0 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
346c0 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
346d0 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
346e0 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
346f0 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
34700 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
34710 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34720 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
34730 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ^An application-
34740 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34750 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
34760 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
34770 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
34780 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
34790 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
347a0 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
347b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
347c0 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
347d0 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
347e0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
347f0 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
34800 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
34810 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
34820 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
34830 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
34840 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
34850 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
34860 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
34870 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
34880 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
34890 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
348a0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
348b0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
348c0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
348d0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
348e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
348f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
34900 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
34910 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
34920 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
34930 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
34940 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
34950 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
34960 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
34970 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
34980 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
34990 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
349a0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
349b0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
349c0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
349d0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
349e0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
349f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34a00 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
34a10 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
34a20 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
34a30 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49  ontext*).);.SQLI
34a40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
34a50 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34a60 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
34a70 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
34a80 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
34a90 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
34aa0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
34ab0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
34ac0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
34ad0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
34ae0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
34af0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
34b00 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
34b10 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
34b20 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
34b30 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
34b40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
34b50 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
34b60 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
34b70 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
34b80 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
34b90 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
34ba0 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
34bb0 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
34bc0 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
34bd0 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
34be0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
34bf0 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
34c00 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
34c10 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
34c20 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
34c30 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
34c40 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
34c50 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
34c60 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
34c70 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
34c80 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
34c90 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
34ca0 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
34cb0 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
34cc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
34cd0 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
34ce0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
34cf0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
34d00 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
34d10 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
34d20 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
34d30 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
34d40 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
34d50 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
34d60 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
34d70 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
34d80 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
34d90 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
34da0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
34db0 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
34dc0 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
34dd0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
34de0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
34df0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
34e00 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
34e10 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
34e20 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
34e30 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
34e40 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
34e50 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
34e60 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
34e70 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
34e80 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
34e90 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
34ea0 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
34eb0 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
34ec0 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  ED.SQLITE_API SQ
34ed0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
34ee0 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
34ef0 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
34f00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
34f10 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
34f20 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
34f30 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
34f40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
34f50 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
34f60 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
34f70 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
34f80 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
34f90 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
34fa0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
34fb0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
34fc0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
34fd0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
34fe0 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
34ff0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
35000 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
35010 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
35020 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
35030 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
35040 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
35050 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
35060 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
35070 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
35080 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
35090 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c         void*,sql
350a0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
350b0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
350c0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
350d0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
350e0 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
350f0 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
35100 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
35110 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
35120 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
35130 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
35140 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
35150 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
35160 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
35170 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
35180 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
35190 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
351a0 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
351b0 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
351c0 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
351d0 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
351e0 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
351f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35200 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
35210 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35220 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
35230 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
35240 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
35250 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
35260 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
35270 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
35280 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
35290 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
352a0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
352b0 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
352c0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
352d0 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
352e0 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
352f0 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
35300 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
35310 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
35320 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
35330 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
35340 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
35350 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
35360 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
35370 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
35380 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
35390 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
353a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
353b0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
353c0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
353d0 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
353e0 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
353f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
35400 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
35410 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
35420 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
35430 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
35440 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
35450 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
35460 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
35470 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
35480 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
35490 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
354a0 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
354b0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
354c0 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
354d0 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
354e0 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
354f0 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
35500 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
35510 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
35520 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
35530 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
35540 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
35550 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
35560 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
35570 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
35580 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
35590 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
355a0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
355b0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
355c0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
355d0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
355e0 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
355f0 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
35600 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
35610 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
35620 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
35630 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
35640 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
35650 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
35660 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
35670 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
35680 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
35690 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
356a0 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
356b0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
356c0 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
356d0 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
356e0 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
356f0 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
35700 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
35710 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
35720 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
35730 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
35740 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
35750 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
35760 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
35770 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
35780 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
35790 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
357a0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
357b0 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
357c0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
357d0 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
357e0 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
357f0 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
35800 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
35810 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
35820 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
35830 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
35840 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
35850 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
35860 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
35870 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
35880 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
35890 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
358a0 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
358b0 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
358c0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
358d0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
358e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
358f0 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
35900 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
35910 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
35920 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
35930 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
35940 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
35950 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
35960 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
35970 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
35980 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
35990 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
359a0 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
359b0 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
359c0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
359d0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
359e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
359f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
35a00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
35a10 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
35a20 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
35a30 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
35a40 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
35a50 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
35a60 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c  E_API double sql
35a70 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
35a80 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
35a90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
35aa0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
35ab0 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
35ac0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
35ad0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
35ae0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
35af0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
35b00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
35b10 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
35b20 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
35b30 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
35b40 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
35b50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
35b60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
35b70 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
35b80 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
35b90 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
35ba0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
35bb0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
35bc0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
35bd0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
35be0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
35bf0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
35c00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
35c10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
35c20 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
35c30 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
35c40 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
35c50 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
35c60 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
35c70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35c80 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
35c90 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
35ca0 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
35cb0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
35cc0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
35cd0 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
35ce0 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
35cf0 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
35d00 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
35d10 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
35d20 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
35d30 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
35d40 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
35d50 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
35d60 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
35d70 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
35d80 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
35d90 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
35da0 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
35db0 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
35dc0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
35dd0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
35de0 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
35df0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
35e00 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
35e10 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
35e20 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
35e30 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
35e40 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
35e50 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
35e60 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
35e70 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
35e80 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
35e90 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
35ea0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
35eb0 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
35ec0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
35ed0 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
35ee0 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
35ef0 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
35f00 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
35f10 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
35f20 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
35f30 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
35f40 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
35f50 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
35f60 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
35f70 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
35f80 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
35f90 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
35fa0 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
35fb0 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
35fc0 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
35fd0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
35fe0 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
35ff0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
36000 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
36010 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
36020 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
36030 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
36040 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
36050 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
36060 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
36070 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73  er .** when firs
36080 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73  t called if N is
36090 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
360a0 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
360b0 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  f a memory.** al
360c0 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
360d0 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
360e0 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
360f0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
36100 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
36110 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
36120 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
36130 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
36140 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
36150 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
36160 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
36170 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
36180 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
36190 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
361a0 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
361b0 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
361c0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
361d0 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
361e0 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
361f0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
36200 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20  .)^  Within the 
36210 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c  xFinal callback,
36220 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79   it is customary
36230 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69   to set.** N=0 i
36240 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  n calls to sqlit
36250 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
36260 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61  text(C,N) so tha
36270 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65  t no .** pointle
36280 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ss memory alloca
36290 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a  tions occur..**.
362a0 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
362b0 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
362c0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
362d0 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
362e0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
362f0 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
36300 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
36310 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
36320 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
36330 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
36340 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
36350 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
36360 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
36370 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
36380 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
36390 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
363a0 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
363b0 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
363c0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
363d0 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
363e0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
363f0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
36400 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
36410 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
36420 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
36430 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
36440 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
36450 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
36460 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61   void *sqlite3_a
36470 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
36480 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36490 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
364a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
364b0 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
364c0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
364d0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
364e0 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
364f0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
36500 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
36510 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
36520 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
36530 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
36540 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
36550 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
36560 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
36570 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
36580 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
36590 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
365a0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
365b0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
365c0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
365d0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
365e0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
365f0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
36600 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
36610 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
36620 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
36630 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
36640 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
36650 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
36660 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
36670 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
36680 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
36690 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
366a0 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
366b0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
366c0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
366d0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
366e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
366f0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
36700 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
36710 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36720 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
36730 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
36740 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
36750 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
36760 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
36770 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
36780 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
36790 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
367a0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
367b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
367c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
367d0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
367e0 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
367f0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
36800 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36810 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36820 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
36830 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
36840 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
36850 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
36860 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
36870 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
36880 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
36890 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
368a0 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
368b0 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
368c0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
368d0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
368e0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
368f0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
36900 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
36910 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
36920 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
36930 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
36940 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
36950 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
36960 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
36970 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
36980 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
36990 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
369a0 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
369b0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
369c0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
369d0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
369e0 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
369f0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
36a00 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
36a10 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20  h the SQL value 
36a20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65  passed as the re
36a30 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
36a40 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68  .** pattern.  Th
36a50 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
36a60 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
36a70 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
36a80 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
36a90 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
36aa0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74  me function so t
36ab0 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  hat the original
36ac0 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a   pattern string.
36ad0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ** does not need
36ae0 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65   to be recompile
36af0 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61  d on each invoca
36b00 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
36b10 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
36b20 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
36b30 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
36b40 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
36b50 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
36b60 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
36b70 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
36b80 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
36b90 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
36ba0 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
36bb0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36bc0 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e   function. ^If n
36bd0 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  o metadata has b
36be0 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e  een ever.** been
36bf0 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68   set for the Nth
36c00 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
36c10 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
36c20 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
36c30 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  ng.** function p
36c40 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61  arameter has cha
36c50 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
36c60 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
36c70 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  ,.** then sqlite
36c80 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
36c90 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
36ca0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
36cb0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
36cc0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
36cd0 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
36ce0 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
36cf0 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
36d00 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
36d10 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
36d20 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
36d30 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
36d40 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36d50 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
36d60 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
36d70 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
36d80 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
36d90 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
36da0 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
36db0 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
36dc0 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   ^If it is not N
36dd0 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
36de0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
36df0 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ructor.** functi
36e00 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
36e10 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
36e20 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
36e30 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
36e40 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74   metadata when t
36e50 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
36e60 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
36e70 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
36e80 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
36e90 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
36ea0 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
36eb0 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
36ec0 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
36ed0 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
36ee0 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
36ef0 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a  metadata on any.
36f00 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ** parameter of 
36f10 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
36f20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  any time.  ^The 
36f30 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69  only guarantee i
36f40 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65  s that.** the de
36f50 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
36f60 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
36f70 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
36f80 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ropped..**.** ^(
36f90 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
36fa0 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
36fb0 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
36fc0 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
36fd0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61   expressions tha
36fe0 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61  t are constant a
36ff0 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  t compile time. 
37000 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69  This includes li
37010 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
37020 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
37030 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .)^.**.** These 
37040 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
37050 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
37060 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
37070 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
37080 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
37090 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
370a0 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
370b0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
370c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
370d0 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
370e0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
370f0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
37100 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
37110 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
37120 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
37130 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37140 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
37150 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
37160 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
37170 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
37180 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
37190 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
371a0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
371b0 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
371c0 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
371d0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
371e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
371f0 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
37200 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
37210 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
37220 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
37230 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
37240 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
37250 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
37260 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
37270 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
37280 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
37290 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
372a0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
372b0 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
372c0 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
372d0 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
372e0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
372f0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
37300 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
37310 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
37320 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
37330 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
37340 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
37350 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
37360 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
37370 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
37380 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
37390 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
373a0 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
373b0 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
373c0 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
373d0 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
373e0 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
373f0 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
37400 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
37410 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
37420 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
37430 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
37440 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
37450 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
37460 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
37470 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
37480 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
37490 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
374a0 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
374b0 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
374c0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
374d0 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
374e0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
374f0 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
37500 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
37510 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
37520 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
37530 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
37540 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
37550 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
37560 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
37570 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
37580 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
37590 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
375a0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
375b0 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
375c0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
375d0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
375e0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
375f0 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
37600 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
37610 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
37620 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
37630 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
37640 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37650 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
37660 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
37670 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
37680 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
37690 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
376a0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
376b0 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
376c0 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
376d0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
376e0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
376f0 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
37700 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
37710 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
37720 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
37730 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37740 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
37750 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
37760 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
37770 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
37780 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
37790 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
377a0 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
377b0 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
377c0 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
377d0 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
377e0 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
377f0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
37800 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37810 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
37820 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
37830 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
37840 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37850 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
37860 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
37870 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
37880 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
37890 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
378a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
378b0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
378c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
378d0 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
378e0 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
378f0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
37900 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
37910 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
37920 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
37930 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
37940 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
37950 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
37960 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37970 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
37980 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
37990 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
379a0 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
379b0 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
379c0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
379d0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
379e0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
379f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37a00 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
37a10 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
37a20 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
37a30 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
37a40 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
37a50 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
37a60 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
37a70 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
37a80 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
37a90 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37aa0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
37ab0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
37ac0 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
37ad0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
37ae0 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
37af0 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
37b00 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
37b10 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
37b20 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
37b30 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
37b40 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
37b50 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
37b60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37b70 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
37b80 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
37b90 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
37ba0 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
37bb0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
37bc0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
37bd0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
37be0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
37bf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37c00 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
37c10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37c20 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
37c30 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
37c40 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
37c50 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
37c60 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
37c70 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
37c80 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
37c90 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
37ca0 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
37cb0 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
37cc0 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
37cd0 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
37ce0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37cf0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
37d00 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
37d10 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
37d20 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
37d30 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
37d40 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
37d50 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
37d60 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
37d70 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
37d80 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
37d90 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
37da0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
37db0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
37dc0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
37dd0 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
37de0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
37df0 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
37e00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37e10 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37e20 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  r_toobig() inter
37e30 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
37e40 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
37e50 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
37e60 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
37e70 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20   or BLOB is too 
37e80 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
37e90 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
37ea0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37eb0 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  or_nomem() inter
37ec0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
37ed0 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
37ee0 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
37ef0 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
37f00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
37f10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
37f20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
37f30 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
37f40 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
37f50 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
37f60 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37f70 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
37f80 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
37f90 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
37fa0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
37fb0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
37fc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
37fd0 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
37fe0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
37ff0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
38000 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
38010 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
38020 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
38030 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
38040 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
38050 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
38060 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
38070 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
38080 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
38090 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
380a0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
380b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
380c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
380d0 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
380e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
380f0 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
38100 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
38110 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
38120 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
38130 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
38140 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
38150 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
38160 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
38170 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
38180 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
38190 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
381a0 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
381b0 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
381c0 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
381d0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
381e0 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
381f0 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
38200 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
38210 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
38220 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69  tively..** ^SQLi
38230 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
38240 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
38250 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
38260 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
38270 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
38280 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
38290 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
382a0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
382b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
382c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
382d0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
382e0 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
382f0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
38300 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
38310 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
38320 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
38330 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
38340 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
38350 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
38360 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
38370 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
38380 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
38390 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
383a0 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
383b0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
383c0 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
383d0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
383e0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
383f0 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
38400 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
38410 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
38420 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68  n result.  If th
38430 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
38440 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
38450 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74   then it.** must
38460 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
38470 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72  set into the str
38480 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55  ing where the NU
38490 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
384a0 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20  ld.** appear if 
384b0 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
384c0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e   NUL terminated.
384d0 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
384e0 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a  racters occur.**
384f0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61   in the string a
38500 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20  t a byte offset 
38510 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61  that is less tha
38520 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  n the value of t
38530 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65  he 3rd.** parame
38540 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ter, then the re
38550 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77  sulting string w
38560 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  ill contain embe
38570 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68  dded NULs and th
38580 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65  e.** result of e
38590 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61  xpressions opera
385a0 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20  ting on strings 
385b0 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
385c0 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
385d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
385e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
385f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38600 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
38610 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
38620 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20  esult_blob is a 
38630 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
38640 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61  , then SQLite ca
38650 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63  lls that.** func
38660 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74  tion as the dest
38670 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65  ructor on the te
38680 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
38690 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a  t when it has.**
386a0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
386b0 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
386c0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
386d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
386e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
386f0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20  * interfaces or 
38700 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  to.** sqlite3_re
38710 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
38720 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
38730 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
38740 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
38750 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
38760 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
38770 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
38780 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
38790 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
387a0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74