System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact d494e8d81607f0515d4f386156fb0fd86d5ba7df:


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 32 2e 31 2e  ersion 3.7.12.1.
00b0: 20 20 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61    By combining a
00c0: 6c 6c 20 74 68 65 20 69 6e 64 69 76 69 64 75 61  ll the individua
00d0: 6c 20 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69  l C code files i
00e0: 6e 74 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e  nto this .** sin
00f0: 67 6c 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20  gle large file, 
0100: 74 68 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20  the entire code 
0110: 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  can be compiled 
0120: 61 73 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e  as a single tran
0130: 73 6c 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e  slation.** unit.
0140: 20 20 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61    This allows ma
0150: 6e 79 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20  ny compilers to 
0160: 64 6f 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  do optimizations
0170: 20 74 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20   that would not 
0180: 62 65 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69  be.** possible i
0190: 66 20 74 68 65 20 66 69 6c 65 73 20 77 65 72 65  f the files were
01a0: 20 63 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61   compiled separa
01b0: 74 65 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e  tely.  Performan
01c0: 63 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a  ce improvements.
01d0: 2a 2a 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65  ** of 5% or more
01e0: 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65   are commonly se
01f0: 65 6e 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  en when SQLite i
0200: 73 20 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20  s compiled as a 
0210: 73 69 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c  single.** transl
0220: 61 74 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a  ation unit..**.*
0230: 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 61  * This file is a
0240: 6c 6c 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63  ll you need to c
0250: 6f 6d 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20  ompile SQLite.  
0260: 54 6f 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e  To use SQLite in
0270: 20 6f 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61   other.** progra
0280: 6d 73 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69  ms, you need thi
0290: 73 20 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22  s file and the "
02a0: 73 71 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65  sqlite3.h" heade
02b0: 72 20 66 69 6c 65 20 74 68 61 74 20 64 65 66 69  r file that defi
02c0: 6e 65 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72  nes.** the progr
02d0: 61 6d 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65  amming interface
02e0: 20 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   to the SQLite l
02f0: 69 62 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75  ibrary.  (If you
0300: 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a   do not have .**
0310: 20 74 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22   the "sqlite3.h"
0320: 20 68 65 61 64 65 72 20 66 69 6c 65 20 61 74 20   header file at 
0330: 68 61 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66  hand, you will f
0340: 69 6e 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64  ind a copy embed
0350: 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  ded within.** th
0360: 65 20 74 65 78 74 20 6f 66 20 74 68 69 73 20 66  e text of this f
0370: 69 6c 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72  ile.  Search for
0380: 20 22 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c   "Begin file sql
0390: 69 74 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20  ite3.h" to find 
03a0: 74 68 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20  the start.** of 
03b0: 74 68 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c  the embedded sql
03c0: 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 69  ite3.h header fi
03d0: 6c 65 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20  le.) Additional 
03e0: 63 6f 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62  code files may b
03f0: 65 20 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79  e needed.** if y
0400: 6f 75 20 77 61 6e 74 20 61 20 77 72 61 70 70 65  ou want a wrappe
0410: 72 20 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53  r to interface S
0420: 51 4c 69 74 65 20 77 69 74 68 20 79 6f 75 72 20  QLite with your 
0430: 63 68 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61  choice of progra
0440: 6d 6d 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67  mming.** languag
0450: 65 2e 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20  e. The code for 
0460: 74 68 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f  the "sqlite3" co
0470: 6d 6d 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c  mmand-line shell
0480: 20 69 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a   is also in a.**
0490: 20 73 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20   separate file. 
04a0: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69  This file contai
04b0: 6e 73 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72  ns only code for
04c0: 20 74 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65   the core SQLite
04d0: 20 6c 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65   library..*/.#de
04e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45  fine SQLITE_CORE
04f0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
0500: 45 5f 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31  E_AMALGAMATION 1
0510: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
0520: 50 52 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65  PRIVATE.# define
0530: 20 53 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20   SQLITE_PRIVATE 
0540: 73 74 61 74 69 63 0a 23 65 6e 64 69 66 0a 23 69  static.#endif.#i
0550: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49  fndef SQLITE_API
0560: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
0570: 5f 41 50 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a  _API.#endif./***
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69  *********** Begi
0590: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74  n file sqliteInt
05a0: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .h *************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a  **********/./*.*
05d0: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72  * 2001 September
05e0: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75   15.**.** The au
05f0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
0600: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
0610: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
0620: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0630: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0640: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
0650: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
0660: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
0670: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0680: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0690: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
06a0: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
06b0: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
06c0: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
06d0: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
06e0: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
06f0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0740: 2a 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69  **.** Internal i
0750: 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74  nterface definit
0760: 69 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e  ions for SQLite.
0770: 0a 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f  .**.*/.#ifndef _
0780: 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65  SQLITEINT_H_.#de
0790: 66 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f  fine _SQLITEINT_
07a0: 48 5f 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20  H_../*.** These 
07b0: 23 64 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20  #defines should 
07c0: 65 6e 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65  enable >2GB file
07d0: 20 73 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49   support on POSI
07e0: 58 20 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  X if the.** unde
07f0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
0800: 20 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73   system supports
0810: 20 69 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20   it.  If the OS 
0820: 6c 61 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66  lacks.** large f
0830: 69 6c 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20  ile support, or 
0840: 69 66 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e  if the OS is win
0850: 64 6f 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75  dows, these shou
0860: 6c 64 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  ld be no-ops..**
0870: 0a 2a 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39  .** Ticket #2739
0880: 3a 20 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c  :  The _LARGEFIL
0890: 45 5f 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d  E_SOURCE macro m
08a0: 75 73 74 20 61 70 70 65 61 72 20 62 65 66 6f 72  ust appear befor
08b0: 65 20 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20  e any.** system 
08c0: 23 69 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63  #includes.  Henc
08d0: 65 2c 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66  e, this block of
08e0: 20 63 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68   code must be th
08f0: 65 20 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20  e very first.** 
0900: 63 6f 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72  code in all sour
0910: 63 65 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  ce files..**.** 
0920: 4c 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f  Large file suppo
0930: 72 74 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c  rt can be disabl
0940: 65 64 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53  ed using the -DS
0950: 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46  QLITE_DISABLE_LF
0960: 53 20 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74  S switch.** on t
0970: 68 65 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d  he compiler comm
0980: 61 6e 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20  and line.  This 
0990: 69 73 20 6e 65 63 65 73 73 61 72 79 20 69 66 20  is necessary if 
09a0: 79 6f 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e  you are compilin
09b0: 67 0a 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74  g.** on a recent
09c0: 20 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65   machine (ex: Re
09d0: 64 20 48 61 74 20 37 2e 32 29 20 62 75 74 20 79  d Hat 7.2) but y
09e0: 6f 75 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64  ou want your cod
09f0: 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20  e to work.** on 
0a00: 61 6e 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65  an older machine
0a10: 20 28 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e   (ex: Red Hat 6.
0a20: 30 29 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70  0).  If you comp
0a30: 69 6c 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37  ile on Red Hat 7
0a40: 2e 32 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68  .2.** without th
0a50: 69 73 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69  is option, LFS i
0a60: 73 20 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c  s enable.  But L
0a70: 46 53 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73  FS does not exis
0a80: 74 20 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a  t in the kernel.
0a90: 2a 2a 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e  ** in Red Hat 6.
0aa0: 30 2c 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77  0, so the code w
0ab0: 6f 6e 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63  on't work.  Henc
0ac0: 65 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62  e, for maximum b
0ad0: 69 6e 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69  inary.** portabi
0ae0: 6c 69 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20  lity you should 
0af0: 6f 6d 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20  omit LFS..**.** 
0b00: 53 69 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20  Similar is true 
0b10: 66 6f 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c  for Mac OS X.  L
0b20: 46 53 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f  FS is only suppo
0b30: 72 74 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58  rted on Mac OS X
0b40: 20 39 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f   9 and later..*/
0b50: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
0b60: 44 49 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65  DISABLE_LFS.# de
0b70: 66 69 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45  fine _LARGE_FILE
0b80: 20 20 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65         1.# ifnde
0b90: 66 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42  f _FILE_OFFSET_B
0ba0: 49 54 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f  ITS.#   define _
0bb0: 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53  FILE_OFFSET_BITS
0bc0: 20 36 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65   64.# endif.# de
0bd0: 66 69 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f  fine _LARGEFILE_
0be0: 53 4f 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a  SOURCE 1.#endif.
0bf0: 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74  ./*.** Include t
0c00: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
0c10: 20 68 65 61 64 65 72 20 6f 75 74 70 75 74 20 62   header output b
0c20: 79 20 27 63 6f 6e 66 69 67 75 72 65 27 20 69 66  y 'configure' if
0c30: 20 77 65 27 72 65 20 75 73 69 6e 67 20 74 68 65   we're using the
0c40: 0a 2a 2a 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73  .** autoconf-bas
0c50: 65 64 20 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64  ed build.*/.#ifd
0c60: 65 66 20 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f  ef _HAVE_SQLITE_
0c70: 43 4f 4e 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64  CONFIG_H.#includ
0c80: 65 20 22 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e  e "config.h".#en
0c90: 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  dif../**********
0ca0: 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c  **** Include sql
0cb0: 69 74 65 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68  iteLimit.h in th
0cc0: 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69  e middle of sqli
0cd0: 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a  teInt.h ********
0ce0: 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ***/./**********
0cf0: 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20  **** Begin file 
0d00: 73 71 6c 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a  sqliteLimit.h **
0d10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d30: 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20  ***/./*.** 2007 
0d40: 4d 61 79 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20  May 7.**.** The 
0d50: 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73  author disclaims
0d60: 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68   copyright to th
0d70: 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20  is source code. 
0d80: 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   In place of.** 
0d90: 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20  a legal notice, 
0da0: 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69  here is a blessi
0db0: 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79  ng:.**.**    May
0dc0: 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64   you do good and
0dd0: 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20   not evil..**   
0de0: 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f   May you find fo
0df0: 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f  rgiveness for yo
0e00: 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69  urself and forgi
0e10: 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20  ve others..**   
0e20: 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66   May you share f
0e30: 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b  reely, never tak
0e40: 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f  ing more than yo
0e50: 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a  u give..**.*****
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ea0: 2a 2a 2a 2a 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73  ****.** .** This
0eb0: 20 66 69 6c 65 20 64 65 66 69 6e 65 73 20 76 61   file defines va
0ec0: 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 6f 66 20  rious limits of 
0ed0: 77 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  what SQLite can 
0ee0: 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a  process..*/../*.
0ef0: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  ** The maximum l
0f00: 65 6e 67 74 68 20 6f 66 20 61 20 54 45 58 54 20  ength of a TEXT 
0f10: 6f 72 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73  or BLOB in bytes
0f20: 2e 20 20 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a  .   This also.**
0f30: 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65   limits the size
0f40: 20 6f 66 20 61 20 72 6f 77 20 69 6e 20 61 20 74   of a row in a t
0f50: 61 62 6c 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a  able or index..*
0f60: 2a 0a 2a 2a 20 54 68 65 20 68 61 72 64 20 6c 69  *.** The hard li
0f70: 6d 69 74 20 69 73 20 74 68 65 20 61 62 69 6c 69  mit is the abili
0f80: 74 79 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73  ty of a 32-bit s
0f90: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
0fa0: 20 74 6f 20 63 6f 75 6e 74 20 74 68 65 20 73 69   to count the si
0fb0: 7a 65 3a 20 32 5e 33 31 2d 31 20 6f 72 20 32 31  ze: 2^31-1 or 21
0fc0: 34 37 34 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66  47483647..*/.#if
0fd0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ndef SQLITE_MAX_
0fe0: 4c 45 4e 47 54 48 0a 23 20 64 65 66 69 6e 65 20  LENGTH.# define 
0ff0: 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54  SQLITE_MAX_LENGT
1000: 48 20 31 30 30 30 30 30 30 30 30 30 0a 23 65 6e  H 1000000000.#en
1010: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20  dif../*.** This 
1020: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  is the maximum n
1030: 75 6d 62 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20  umber of.**.**  
1040: 20 20 2a 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61    * Columns in a
1050: 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43   table.**    * C
1060: 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
1070: 65 78 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d  ex.**    * Colum
1080: 6e 73 20 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20  ns in a view.** 
1090: 20 20 20 2a 20 54 65 72 6d 73 20 69 6e 20 74 68     * Terms in th
10a0: 65 20 53 45 54 20 63 6c 61 75 73 65 20 6f 66 20  e SET clause of 
10b0: 61 6e 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  an UPDATE statem
10c0: 65 6e 74 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d  ent.**    * Term
10d0: 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
10e0: 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20  set of a SELECT 
10f0: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20  statement.**    
1100: 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20 47  * Terms in the G
1110: 52 4f 55 50 20 42 59 20 6f 72 20 4f 52 44 45 52  ROUP BY or ORDER
1120: 20 42 59 20 63 6c 61 75 73 65 73 20 6f 66 20 61   BY clauses of a
1130: 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1140: 74 2e 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73  t..**    * Terms
1150: 20 69 6e 20 74 68 65 20 56 41 4c 55 45 53 20 63   in the VALUES c
1160: 6c 61 75 73 65 20 6f 66 20 61 6e 20 49 4e 53 45  lause of an INSE
1170: 52 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  RT statement.**.
1180: 2a 2a 20 54 68 65 20 68 61 72 64 20 75 70 70 65  ** The hard uppe
1190: 72 20 6c 69 6d 69 74 20 68 65 72 65 20 69 73 20  r limit here is 
11a0: 33 32 36 37 36 2e 20 20 4d 6f 73 74 20 64 61 74  32676.  Most dat
11b0: 61 62 61 73 65 20 70 65 6f 70 6c 65 20 77 69 6c  abase people wil
11c0: 6c 0a 2a 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68  l.** tell you th
11d0: 61 74 20 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72  at in a well-nor
11e0: 6d 61 6c 69 7a 65 64 20 64 61 74 61 62 61 73 65  malized database
11f0: 2c 20 79 6f 75 20 75 73 75 61 6c 6c 79 20 73 68  , you usually sh
1200: 6f 75 6c 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65  ould.** not have
1210: 20 6d 6f 72 65 20 74 68 61 6e 20 61 20 64 6f 7a   more than a doz
1220: 65 6e 20 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73  en or so columns
1230: 20 69 6e 20 61 6e 79 20 74 61 62 6c 65 2e 20 20   in any table.  
1240: 41 6e 64 20 69 66 0a 2a 2a 20 74 68 61 74 20 69  And if.** that i
1250: 73 20 74 68 65 20 63 61 73 65 2c 20 74 68 65 72  s the case, ther
1260: 65 20 69 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e  e is no point in
1270: 20 68 61 76 69 6e 67 20 6d 6f 72 65 20 74 68 61   having more tha
1280: 6e 20 61 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e  n a few.** dozen
1290: 20 76 61 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f   values in any o
12a0: 66 20 74 68 65 20 6f 74 68 65 72 20 73 69 74 75  f the other situ
12b0: 61 74 69 6f 6e 73 20 64 65 73 63 72 69 62 65 64  ations described
12c0: 20 61 62 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64   above..*/.#ifnd
12d0: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f  ef SQLITE_MAX_CO
12e0: 4c 55 4d 4e 0a 23 20 64 65 66 69 6e 65 20 53 51  LUMN.# define SQ
12f0: 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20  LITE_MAX_COLUMN 
1300: 32 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  2000.#endif../*.
1310: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  ** The maximum l
1320: 65 6e 67 74 68 20 6f 66 20 61 20 73 69 6e 67 6c  ength of a singl
1330: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1340: 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20  in bytes..**.** 
1350: 49 74 20 75 73 65 64 20 74 6f 20 62 65 20 74 68  It used to be th
1360: 65 20 63 61 73 65 20 74 68 61 74 20 73 65 74 74  e case that sett
1370: 69 6e 67 20 74 68 69 73 20 76 61 6c 75 65 20 74  ing this value t
1380: 6f 20 7a 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20  o zero would.** 
1390: 74 75 72 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f  turn the limit o
13a0: 66 66 2e 20 20 54 68 61 74 20 69 73 20 6e 6f 20  ff.  That is no 
13b0: 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 49 74  longer true.  It
13c0: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
13d0: 0a 2a 2a 20 74 6f 20 74 75 72 6e 20 74 68 69 73  .** to turn this
13e0: 20 6c 69 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23   limit off..*/.#
13f0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41  ifndef SQLITE_MA
1400: 58 5f 53 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64  X_SQL_LENGTH.# d
1410: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58  efine SQLITE_MAX
1420: 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30  _SQL_LENGTH 1000
1430: 30 30 30 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f  000000.#endif../
1440: 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d  *.** The maximum
1450: 20 64 65 70 74 68 20 6f 66 20 61 6e 20 65 78 70   depth of an exp
1460: 72 65 73 73 69 6f 6e 20 74 72 65 65 2e 20 54 68  ression tree. Th
1470: 69 73 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  is is limited to
1480: 20 0a 2a 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74   .** some extent
1490: 20 62 79 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53   by SQLITE_MAX_S
14a0: 51 4c 5f 4c 45 4e 47 54 48 2e 20 42 75 74 20 73  QL_LENGTH. But s
14b0: 6f 6d 65 74 69 6d 65 20 79 6f 75 20 6d 69 67 68  ometime you migh
14c0: 74 20 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c  t .** want to pl
14d0: 61 63 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20  ace more severe 
14e0: 6c 69 6d 69 74 73 20 6f 6e 20 74 68 65 20 63 6f  limits on the co
14f0: 6d 70 6c 65 78 69 74 79 20 6f 66 20 61 6e 20 0a  mplexity of an .
1500: 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a  ** expression..*
1510: 2a 0a 2a 2a 20 41 20 76 61 6c 75 65 20 6f 66 20  *.** A value of 
1520: 30 20 75 73 65 64 20 74 6f 20 6d 65 61 6e 20 74  0 used to mean t
1530: 68 61 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61  hat the limit wa
1540: 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a  s not enforced..
1550: 2a 2a 20 42 75 74 20 74 68 61 74 20 69 73 20 6e  ** But that is n
1560: 6f 20 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20  o longer true.  
1570: 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77  The limit is now
1580: 20 73 74 72 69 63 74 6c 79 20 65 6e 66 6f 72 63   strictly enforc
1590: 65 64 0a 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d  ed.** at all tim
15a0: 65 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  es..*/.#ifndef S
15b0: 51 4c 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44  QLITE_MAX_EXPR_D
15c0: 45 50 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51  EPTH.# define SQ
15d0: 4c 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45  LITE_MAX_EXPR_DE
15e0: 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a  PTH 1000.#endif.
15f0: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d  ./*.** The maxim
1600: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
1610: 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
1620: 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1630: 74 2e 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 67  t..** The code g
1640: 65 6e 65 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d  enerator for com
1650: 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
1660: 74 65 6d 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65  tements does one
1670: 0a 2a 2a 20 6c 65 76 65 6c 20 6f 66 20 72 65 63  .** level of rec
1680: 75 72 73 69 6f 6e 20 66 6f 72 20 65 61 63 68 20  ursion for each 
1690: 74 65 72 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f  term.  A stack o
16a0: 76 65 72 66 6c 6f 77 20 63 61 6e 20 72 65 73 75  verflow can resu
16b0: 6c 74 0a 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d  lt.** if the num
16c0: 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 73 20  ber of terms is 
16d0: 74 6f 6f 20 6c 61 72 67 65 2e 20 20 49 6e 20 70  too large.  In p
16e0: 72 61 63 74 69 63 65 2c 20 6d 6f 73 74 20 53 51  ractice, most SQ
16f0: 4c 0a 2a 2a 20 6e 65 76 65 72 20 68 61 73 20 6d  L.** never has m
1700: 6f 72 65 20 74 68 61 6e 20 33 20 6f 72 20 34 20  ore than 3 or 4 
1710: 74 65 72 6d 73 2e 20 20 55 73 65 20 61 20 76 61  terms.  Use a va
1720: 6c 75 65 20 6f 66 20 30 20 74 6f 20 64 69 73 61  lue of 0 to disa
1730: 62 6c 65 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74  ble.** any limit
1740: 20 6f 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   on the number o
1750: 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
1760: 70 6f 75 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f  pount SELECT..*/
1770: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
1780: 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MAX_COMPOUND_SEL
1790: 45 43 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ECT.# define SQL
17a0: 49 54 45 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44  ITE_MAX_COMPOUND
17b0: 5f 53 45 4c 45 43 54 20 35 30 30 0a 23 65 6e 64  _SELECT 500.#end
17c0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61  if../*.** The ma
17d0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
17e0: 6f 70 63 6f 64 65 73 20 69 6e 20 61 20 56 44 42  opcodes in a VDB
17f0: 45 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f  E program..** No
1800: 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f  t currently enfo
1810: 72 63 65 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  rced..*/.#ifndef
1820: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45   SQLITE_MAX_VDBE
1830: 5f 4f 50 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  _OP.# define SQL
1840: 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20  ITE_MAX_VDBE_OP 
1850: 32 35 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a  25000.#endif../*
1860: 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20  .** The maximum 
1870: 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
1880: 6e 74 73 20 74 6f 20 61 6e 20 53 51 4c 20 66 75  nts to an SQL fu
1890: 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64  nction..*/.#ifnd
18a0: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55  ef SQLITE_MAX_FU
18b0: 4e 43 54 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66  NCTION_ARG.# def
18c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46  ine SQLITE_MAX_F
18d0: 55 4e 43 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a  UNCTION_ARG 127.
18e0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
18f0: 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1900: 20 6f 66 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61   of in-memory pa
1910: 67 65 73 20 74 6f 20 75 73 65 20 66 6f 72 20 74  ges to use for t
1920: 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
1930: 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 66 6f  .** table and fo
1940: 72 20 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c  r temporary tabl
1950: 65 73 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  es.  The SQLITE_
1960: 44 45 46 41 55 4c 54 5f 43 41 43 48 45 5f 53 49  DEFAULT_CACHE_SI
1970: 5a 45 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  ZE.*/.#ifndef SQ
1980: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43  LITE_DEFAULT_CAC
1990: 48 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65  HE_SIZE.# define
19a0: 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f   SQLITE_DEFAULT_
19b0: 43 41 43 48 45 5f 53 49 5a 45 20 20 32 30 30 30  CACHE_SIZE  2000
19c0: 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20  .#endif.#ifndef 
19d0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 54  SQLITE_DEFAULT_T
19e0: 45 4d 50 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23  EMP_CACHE_SIZE.#
19f0: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44   define SQLITE_D
1a00: 45 46 41 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48  EFAULT_TEMP_CACH
1a10: 45 5f 53 49 5a 45 20 20 35 30 30 0a 23 65 6e 64  E_SIZE  500.#end
1a20: 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65  if../*.** The de
1a30: 66 61 75 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20  fault number of 
1a40: 66 72 61 6d 65 73 20 74 6f 20 61 63 63 75 6d 75  frames to accumu
1a50: 6c 61 74 65 20 69 6e 20 74 68 65 20 6c 6f 67 20  late in the log 
1a60: 66 69 6c 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63  file before.** c
1a70: 68 65 63 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65  heckpointing the
1a80: 20 64 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c   database in WAL
1a90: 20 6d 6f 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65   mode..*/.#ifnde
1aa0: 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54  f SQLITE_DEFAULT
1ab0: 5f 57 41 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f  _WAL_AUTOCHECKPO
1ac0: 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  INT.# define SQL
1ad0: 49 54 45 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f  ITE_DEFAULT_WAL_
1ae0: 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20  AUTOCHECKPOINT  
1af0: 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  1000.#endif../*.
1b00: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  ** The maximum n
1b10: 75 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68 65  umber of attache
1b20: 64 20 64 61 74 61 62 61 73 65 73 2e 20 20 54 68  d databases.  Th
1b30: 69 73 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  is must be betwe
1b40: 65 6e 20 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20  en 0.** and 62. 
1b50: 20 54 68 65 20 75 70 70 65 72 20 62 6f 75 6e 64   The upper bound
1b60: 20 6f 6e 20 36 32 20 69 73 20 62 65 63 61 75 73   on 62 is becaus
1b70: 65 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67  e a 64-bit integ
1b80: 65 72 20 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20  er bitmap.** is 
1b90: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
1ba0: 74 6f 20 74 72 61 63 6b 20 61 74 74 61 63 68 65  to track attache
1bb0: 64 20 64 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a  d databases..*/.
1bc0: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  #ifndef SQLITE_M
1bd0: 41 58 5f 41 54 54 41 43 48 45 44 0a 23 20 64 65  AX_ATTACHED.# de
1be0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f  fine SQLITE_MAX_
1bf0: 41 54 54 41 43 48 45 44 20 31 30 0a 23 65 6e 64  ATTACHED 10.#end
1c00: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d  if.../*.** The m
1c10: 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20  aximum value of 
1c20: 61 20 3f 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20  a ?nnn wildcard 
1c30: 74 68 61 74 20 74 68 65 20 70 61 72 73 65 72 20  that the parser 
1c40: 77 69 6c 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a  will accept..*/.
1c50: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  #ifndef SQLITE_M
1c60: 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  AX_VARIABLE_NUMB
1c70: 45 52 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  ER.# define SQLI
1c80: 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f  TE_MAX_VARIABLE_
1c90: 4e 55 4d 42 45 52 20 39 39 39 0a 23 65 6e 64 69  NUMBER 999.#endi
1ca0: 66 0a 0a 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61  f../* Maximum pa
1cb0: 67 65 20 73 69 7a 65 2e 20 20 54 68 65 20 75 70  ge size.  The up
1cc0: 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69  per bound on thi
1cd0: 73 20 76 61 6c 75 65 20 69 73 20 36 35 35 33 36  s value is 65536
1ce0: 2e 20 20 54 68 69 73 20 61 20 6c 69 6d 69 74 0a  .  This a limit.
1cf0: 2a 2a 20 69 6d 70 6f 73 65 64 20 62 79 20 74 68  ** imposed by th
1d00: 65 20 75 73 65 20 6f 66 20 31 36 2d 62 69 74 20  e use of 16-bit 
1d10: 6f 66 66 73 65 74 73 20 77 69 74 68 69 6e 20 65  offsets within e
1d20: 61 63 68 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20  ach page..**.** 
1d30: 45 61 72 6c 69 65 72 20 76 65 72 73 69 6f 6e 73  Earlier versions
1d40: 20 6f 66 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77   of SQLite allow
1d50: 65 64 20 74 68 65 20 75 73 65 72 20 74 6f 20 63  ed the user to c
1d60: 68 61 6e 67 65 20 74 68 69 73 20 76 61 6c 75 65  hange this value
1d70: 20 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74   at.** compile t
1d80: 69 6d 65 2e 20 54 68 69 73 20 69 73 20 6e 6f 20  ime. This is no 
1d90: 6c 6f 6e 67 65 72 20 70 65 72 6d 69 74 74 65 64  longer permitted
1da0: 2c 20 6f 6e 20 74 68 65 20 67 72 6f 75 6e 64 73  , on the grounds
1db0: 20 74 68 61 74 20 69 74 20 63 72 65 61 74 65 73   that it creates
1dc0: 0a 2a 2a 20 61 20 6c 69 62 72 61 72 79 20 74 68  .** a library th
1dd0: 61 74 20 69 73 20 74 65 63 68 6e 69 63 61 6c 6c  at is technicall
1de0: 79 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77  y incompatible w
1df0: 69 74 68 20 61 6e 20 53 51 4c 69 74 65 20 6c 69  ith an SQLite li
1e00: 62 72 61 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c  brary .** compil
1e10: 65 64 20 77 69 74 68 20 61 20 64 69 66 66 65 72  ed with a differ
1e20: 65 6e 74 20 6c 69 6d 69 74 2e 20 49 66 20 61 20  ent limit. If a 
1e30: 70 72 6f 63 65 73 73 20 6f 70 65 72 61 74 69 6e  process operatin
1e40: 67 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  g on a database 
1e50: 0a 2a 2a 20 77 69 74 68 20 61 20 70 61 67 65 2d  .** with a page-
1e60: 73 69 7a 65 20 6f 66 20 36 35 35 33 36 20 62 79  size of 65536 by
1e70: 74 65 73 20 63 72 61 73 68 65 73 2c 20 74 68 65  tes crashes, the
1e80: 6e 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  n an instance of
1e90: 20 53 51 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70   SQLite .** comp
1ea0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 64 65  iled with the de
1eb0: 66 61 75 6c 74 20 70 61 67 65 2d 73 69 7a 65 20  fault page-size 
1ec0: 6c 69 6d 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62  limit will not b
1ed0: 65 20 61 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61  e able to rollba
1ee0: 63 6b 20 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74  ck .** the abort
1ef0: 65 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ed transaction. 
1f00: 54 68 69 73 20 63 6f 75 6c 64 20 6c 65 61 64 20  This could lead 
1f10: 74 6f 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  to database corr
1f20: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65  uption..*/.#ifde
1f30: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47  f SQLITE_MAX_PAG
1f40: 45 5f 53 49 5a 45 0a 23 20 75 6e 64 65 66 20 53  E_SIZE.# undef S
1f50: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53  QLITE_MAX_PAGE_S
1f60: 49 5a 45 0a 23 65 6e 64 69 66 0a 23 64 65 66 69  IZE.#endif.#defi
1f70: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41  ne SQLITE_MAX_PA
1f80: 47 45 5f 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a  GE_SIZE 65536...
1f90: 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  /*.** The defaul
1fa0: 74 20 73 69 7a 65 20 6f 66 20 61 20 64 61 74 61  t size of a data
1fb0: 62 61 73 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69  base page..*/.#i
1fc0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46  fndef SQLITE_DEF
1fd0: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23  AULT_PAGE_SIZE.#
1fe0: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44   define SQLITE_D
1ff0: 45 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45  EFAULT_PAGE_SIZE
2000: 20 31 30 32 34 0a 23 65 6e 64 69 66 0a 23 69 66   1024.#endif.#if
2010: 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f   SQLITE_DEFAULT_
2020: 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45  PAGE_SIZE>SQLITE
2030: 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23  _MAX_PAGE_SIZE.#
2040: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45   undef SQLITE_DE
2050: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a  FAULT_PAGE_SIZE.
2060: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2070: 44 45 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a  DEFAULT_PAGE_SIZ
2080: 45 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47  E SQLITE_MAX_PAG
2090: 45 5f 53 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f  E_SIZE.#endif../
20a0: 2a 0a 2a 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c  *.** Ordinarily,
20b0: 20 69 66 20 6e 6f 20 76 61 6c 75 65 20 69 73 20   if no value is 
20c0: 65 78 70 6c 69 63 69 74 6c 79 20 70 72 6f 76 69  explicitly provi
20d0: 64 65 64 2c 20 53 51 4c 69 74 65 20 63 72 65 61  ded, SQLite crea
20e0: 74 65 73 20 64 61 74 61 62 61 73 65 73 0a 2a 2a  tes databases.**
20f0: 20 77 69 74 68 20 70 61 67 65 20 73 69 7a 65 20   with page size 
2100: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50  SQLITE_DEFAULT_P
2110: 41 47 45 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65  AGE_SIZE. Howeve
2120: 72 2c 20 62 61 73 65 64 20 6f 6e 20 63 65 72 74  r, based on cert
2130: 61 69 6e 0a 2a 2a 20 64 65 76 69 63 65 20 63 68  ain.** device ch
2140: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 28 73  aracteristics (s
2150: 65 63 74 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61  ector-size and a
2160: 74 6f 6d 69 63 20 77 72 69 74 65 28 29 20 73 75  tomic write() su
2170: 70 70 6f 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74  pport),.** SQLit
2180: 65 20 6d 61 79 20 63 68 6f 6f 73 65 20 61 20 6c  e may choose a l
2190: 61 72 67 65 72 20 76 61 6c 75 65 2e 20 54 68 69  arger value. Thi
21a0: 73 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 74 68  s constant is th
21b0: 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a  e maximum value.
21c0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63  ** SQLite will c
21d0: 68 6f 6f 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e  hoose on its own
21e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
21f0: 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f  ITE_MAX_DEFAULT_
2200: 50 41 47 45 5f 53 49 5a 45 0a 23 20 64 65 66 69  PAGE_SIZE.# defi
2210: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45  ne SQLITE_MAX_DE
2220: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20  FAULT_PAGE_SIZE 
2230: 38 31 39 32 0a 23 65 6e 64 69 66 0a 23 69 66 20  8192.#endif.#if 
2240: 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55  SQLITE_MAX_DEFAU
2250: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c  LT_PAGE_SIZE>SQL
2260: 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a  ITE_MAX_PAGE_SIZ
2270: 45 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  E.# undef SQLITE
2280: 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47  _MAX_DEFAULT_PAG
2290: 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20  E_SIZE.# define 
22a0: 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55  SQLITE_MAX_DEFAU
22b0: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 53 51 4c  LT_PAGE_SIZE SQL
22c0: 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a  ITE_MAX_PAGE_SIZ
22d0: 45 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a  E.#endif.../*.**
22e0: 20 4d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   Maximum number 
22f0: 6f 66 20 70 61 67 65 73 20 69 6e 20 6f 6e 65 20  of pages in one 
2300: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
2310: 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 72 65 61  *.** This is rea
2320: 6c 6c 79 20 6a 75 73 74 20 74 68 65 20 64 65 66  lly just the def
2330: 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
2340: 68 65 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  he max_page_coun
2350: 74 20 70 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69  t pragma..** Thi
2360: 73 20 76 61 6c 75 65 20 63 61 6e 20 62 65 20 6c  s value can be l
2370: 6f 77 65 72 65 64 20 28 6f 72 20 72 61 69 73 65  owered (or raise
2380: 64 29 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  d) at run-time u
2390: 73 69 6e 67 20 74 68 61 74 20 74 68 65 0a 2a 2a  sing that the.**
23a0: 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20   max_page_count 
23b0: 6d 61 63 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  macro..*/.#ifnde
23c0: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47  f SQLITE_MAX_PAG
23d0: 45 5f 43 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65  E_COUNT.# define
23e0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45   SQLITE_MAX_PAGE
23f0: 5f 43 4f 55 4e 54 20 31 30 37 33 37 34 31 38 32  _COUNT 107374182
2400: 33 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  3.#endif../*.** 
2410: 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28  Maximum length (
2420: 69 6e 20 62 79 74 65 73 29 20 6f 66 20 74 68 65  in bytes) of the
2430: 20 70 61 74 74 65 72 6e 20 69 6e 20 61 20 4c 49   pattern in a LI
2440: 4b 45 20 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70  KE or GLOB.** op
2450: 65 72 61 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64  erator..*/.#ifnd
2460: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49  ef SQLITE_MAX_LI
2470: 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
2480: 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  H.# define SQLIT
2490: 45 5f 4d 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45  E_MAX_LIKE_PATTE
24a0: 52 4e 5f 4c 45 4e 47 54 48 20 35 30 30 30 30 0a  RN_LENGTH 50000.
24b0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61  #endif../*.** Ma
24c0: 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
24d0: 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
24e0: 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76  ggers..**.** A v
24f0: 61 6c 75 65 20 6f 66 20 31 20 6d 65 61 6e 73 20  alue of 1 means 
2500: 74 68 61 74 20 61 20 74 72 69 67 67 65 72 20 70  that a trigger p
2510: 72 6f 67 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20  rogram will not 
2520: 62 65 20 61 62 6c 65 20 74 6f 20 69 74 73 65 6c  be able to itsel
2530: 66 0a 2a 2a 20 66 69 72 65 20 61 6e 79 20 74 72  f.** fire any tr
2540: 69 67 67 65 72 73 2e 20 41 20 76 61 6c 75 65 20  iggers. A value 
2550: 6f 66 20 30 20 6d 65 61 6e 73 20 74 68 61 74 20  of 0 means that 
2560: 6e 6f 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  no trigger progr
2570: 61 6d 73 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d  ams at all .** m
2580: 61 79 20 62 65 20 65 78 65 63 75 74 65 64 2e 0a  ay be executed..
2590: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
25a0: 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45  E_MAX_TRIGGER_DE
25b0: 50 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  PTH.# define SQL
25c0: 49 54 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f  ITE_MAX_TRIGGER_
25d0: 44 45 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69  DEPTH 1000.#endi
25e0: 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  f../************
25f0: 2a 2a 20 45 6e 64 20 6f 66 20 73 71 6c 69 74 65  ** End of sqlite
2600: 4c 69 6d 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a  Limit.h ********
2610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2630: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
2640: 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68  ** Continuing wh
2650: 65 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20  ere we left off 
2660: 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a  in sqliteInt.h *
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2680: 2a 2f 0a 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e  */../* Disable n
2690: 75 69 73 61 6e 63 65 20 77 61 72 6e 69 6e 67 73  uisance warnings
26a0: 20 6f 6e 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70   on Borland comp
26b0: 69 6c 65 72 73 20 2a 2f 0a 23 69 66 20 64 65 66  ilers */.#if def
26c0: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
26d0: 5f 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20  _).#pragma warn 
26e0: 2d 72 63 68 20 2f 2a 20 75 6e 72 65 61 63 68 61  -rch /* unreacha
26f0: 62 6c 65 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61  ble code */.#pra
2700: 67 6d 61 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a  gma warn -ccc /*
2710: 20 43 6f 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c   Condition is al
2720: 77 61 79 73 20 74 72 75 65 20 6f 72 20 66 61 6c  ways true or fal
2730: 73 65 20 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61  se */.#pragma wa
2740: 72 6e 20 2d 61 75 73 20 2f 2a 20 41 73 73 69 67  rn -aus /* Assig
2750: 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6e 65 76  ned value is nev
2760: 65 72 20 75 73 65 64 20 2a 2f 0a 23 70 72 61 67  er used */.#prag
2770: 6d 61 20 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20  ma warn -csu /* 
2780: 43 6f 6d 70 61 72 69 6e 67 20 73 69 67 6e 65 64  Comparing signed
2790: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f   and unsigned */
27a0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 73  .#pragma warn -s
27b0: 70 61 20 2f 2a 20 53 75 73 70 69 63 69 6f 75 73  pa /* Suspicious
27c0: 20 70 6f 69 6e 74 65 72 20 61 72 69 74 68 6d 65   pointer arithme
27d0: 74 69 63 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f  tic */.#endif../
27e0: 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 76 61 72  * Needed for var
27f0: 69 6f 75 73 20 64 65 66 69 6e 69 74 69 6f 6e 73  ious definitions
2800: 2e 2e 2e 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f  ... */.#ifndef _
2810: 47 4e 55 5f 53 4f 55 52 43 45 0a 23 20 64 65 66  GNU_SOURCE.# def
2820: 69 6e 65 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a  ine _GNU_SOURCE.
2830: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e  #endif../*.** In
2840: 63 6c 75 64 65 20 73 74 61 6e 64 61 72 64 20 68  clude standard h
2850: 65 61 64 65 72 20 66 69 6c 65 73 20 61 73 20 6e  eader files as n
2860: 65 63 65 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64  ecessary.*/.#ifd
2870: 65 66 20 48 41 56 45 5f 53 54 44 49 4e 54 5f 48  ef HAVE_STDINT_H
2880: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e  .#include <stdin
2890: 74 2e 68 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64  t.h>.#endif.#ifd
28a0: 65 66 20 48 41 56 45 5f 49 4e 54 54 59 50 45 53  ef HAVE_INTTYPES
28b0: 5f 48 0a 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74  _H.#include <int
28c0: 74 79 70 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a  types.h>.#endif.
28d0: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  ./*.** The follo
28e0: 77 69 6e 67 20 6d 61 63 72 6f 73 20 61 72 65 20  wing macros are 
28f0: 75 73 65 64 20 74 6f 20 63 61 73 74 20 70 6f 69  used to cast poi
2900: 6e 74 65 72 73 20 74 6f 20 69 6e 74 65 67 65 72  nters to integer
2910: 73 20 61 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  s and.** integer
2920: 73 20 74 6f 20 70 6f 69 6e 74 65 72 73 2e 20 20  s to pointers.  
2930: 54 68 65 20 77 61 79 20 79 6f 75 20 64 6f 20 74  The way you do t
2940: 68 69 73 20 76 61 72 69 65 73 20 66 72 6f 6d 20  his varies from 
2950: 6f 6e 65 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20  one compiler.** 
2960: 74 6f 20 74 68 65 20 6e 65 78 74 2c 20 73 6f 20  to the next, so 
2970: 77 65 20 68 61 76 65 20 64 65 76 65 6c 6f 70 65  we have develope
2980: 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
2990: 73 65 74 20 6f 66 20 23 69 66 20 73 74 61 74 65  set of #if state
29a0: 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 67 65 6e 65  ments.** to gene
29b0: 72 61 74 65 20 61 70 70 72 6f 70 72 69 61 74 65  rate appropriate
29c0: 20 6d 61 63 72 6f 73 20 66 6f 72 20 61 20 77 69   macros for a wi
29d0: 64 65 20 72 61 6e 67 65 20 6f 66 20 63 6f 6d 70  de range of comp
29e0: 69 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ilers..**.** The
29f0: 20 63 6f 72 72 65 63 74 20 22 41 4e 53 49 22 20   correct "ANSI" 
2a00: 77 61 79 20 74 6f 20 64 6f 20 74 68 69 73 20 69  way to do this i
2a10: 73 20 74 6f 20 75 73 65 20 74 68 65 20 69 6e 74  s to use the int
2a20: 70 74 72 5f 74 20 74 79 70 65 2e 20 0a 2a 2a 20  ptr_t type. .** 
2a30: 55 6e 66 6f 72 74 75 6e 61 74 65 6c 79 2c 20 74  Unfortunately, t
2a40: 68 61 74 20 74 79 70 65 64 65 66 20 69 73 20 6e  hat typedef is n
2a50: 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20  ot available on 
2a60: 61 6c 6c 20 63 6f 6d 70 69 6c 65 72 73 2c 20 6f  all compilers, o
2a70: 72 0a 2a 2a 20 69 66 20 69 74 20 69 73 20 61 76  r.** if it is av
2a80: 61 69 6c 61 62 6c 65 2c 20 69 74 20 72 65 71 75  ailable, it requ
2a90: 69 72 65 73 20 61 6e 20 23 69 6e 63 6c 75 64 65  ires an #include
2aa0: 20 6f 66 20 73 70 65 63 69 66 69 63 20 68 65 61   of specific hea
2ab0: 64 65 72 73 0a 2a 2a 20 74 68 61 74 20 76 61 72  ders.** that var
2ac0: 79 20 66 72 6f 6d 20 6f 6e 65 20 6d 61 63 68 69  y from one machi
2ad0: 6e 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  ne to the next..
2ae0: 2a 2a 0a 2a 2a 20 54 69 63 6b 65 74 20 23 33 38  **.** Ticket #38
2af0: 36 30 3a 20 20 54 68 65 20 6c 6c 76 6d 2d 67 63  60:  The llvm-gc
2b00: 63 2d 34 2e 32 20 63 6f 6d 70 69 6c 65 72 20 66  c-4.2 compiler f
2b10: 72 6f 6d 20 41 70 70 6c 65 20 63 68 6f 6b 65 73  rom Apple chokes
2b20: 20 6f 6e 0a 2a 2a 20 74 68 65 20 28 28 76 6f 69   on.** the ((voi
2b30: 64 2a 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58  d*)&((char*)0)[X
2b40: 5d 29 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 42  ]) construct.  B
2b50: 75 74 20 4d 53 56 43 20 63 68 6f 6b 65 73 20 6f  ut MSVC chokes o
2b60: 6e 20 28 28 76 6f 69 64 2a 29 28 58 29 29 2e 0a  n ((void*)(X))..
2b70: 2a 2a 20 53 6f 20 77 65 20 68 61 76 65 20 74 6f  ** So we have to
2b80: 20 64 65 66 69 6e 65 20 74 68 65 20 6d 61 63 72   define the macr
2b90: 6f 73 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  os in different 
2ba0: 77 61 79 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ways depending o
2bb0: 6e 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  n the.** compile
2bc0: 72 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  r..*/.#if define
2bd0: 64 28 5f 5f 50 54 52 44 49 46 46 5f 54 59 50 45  d(__PTRDIFF_TYPE
2be0: 5f 5f 29 20 20 2f 2a 20 54 68 69 73 20 63 61 73  __)  /* This cas
2bf0: 65 20 73 68 6f 75 6c 64 20 77 6f 72 6b 20 66 6f  e should work fo
2c00: 72 20 47 43 43 20 2a 2f 0a 23 20 64 65 66 69 6e  r GCC */.# defin
2c10: 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f  e SQLITE_INT_TO_
2c20: 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29  PTR(X)  ((void*)
2c30: 28 5f 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f  (__PTRDIFF_TYPE_
2c40: 5f 29 28 58 29 29 0a 23 20 64 65 66 69 6e 65 20  _)(X)).# define 
2c50: 53 51 4c 49 54 45 5f 50 54 52 5f 54 4f 5f 49 4e  SQLITE_PTR_TO_IN
2c60: 54 28 58 29 20 20 28 28 69 6e 74 29 28 5f 5f 50  T(X)  ((int)(__P
2c70: 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 58  TRDIFF_TYPE__)(X
2c80: 29 29 0a 23 65 6c 69 66 20 21 64 65 66 69 6e 65  )).#elif !define
2c90: 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 20 20 20 20  d(__GNUC__)     
2ca0: 20 20 2f 2a 20 57 6f 72 6b 73 20 66 6f 72 20 63    /* Works for c
2cb0: 6f 6d 70 69 6c 65 72 73 20 6f 74 68 65 72 20 74  ompilers other t
2cc0: 68 61 6e 20 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65  han LLVM */.# de
2cd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f  fine SQLITE_INT_
2ce0: 54 4f 5f 50 54 52 28 58 29 20 20 28 28 76 6f 69  TO_PTR(X)  ((voi
2cf0: 64 2a 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58  d*)&((char*)0)[X
2d00: 5d 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  ]).# define SQLI
2d10: 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29  TE_PTR_TO_INT(X)
2d20: 20 20 28 28 69 6e 74 29 28 28 28 63 68 61 72 2a    ((int)(((char*
2d30: 29 58 29 2d 28 63 68 61 72 2a 29 30 29 29 0a 23  )X)-(char*)0)).#
2d40: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 48 41 56  elif defined(HAV
2d50: 45 5f 53 54 44 49 4e 54 5f 48 29 20 20 20 2f 2a  E_STDINT_H)   /*
2d60: 20 55 73 65 20 74 68 69 73 20 63 61 73 65 20 69   Use this case i
2d70: 66 20 77 65 20 68 61 76 65 20 41 4e 53 49 20 68  f we have ANSI h
2d80: 65 61 64 65 72 73 20 2a 2f 0a 23 20 64 65 66 69  eaders */.# defi
2d90: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f  ne SQLITE_INT_TO
2da0: 5f 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a  _PTR(X)  ((void*
2db0: 29 28 69 6e 74 70 74 72 5f 74 29 28 58 29 29 0a  )(intptr_t)(X)).
2dc0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2dd0: 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28  PTR_TO_INT(X)  (
2de0: 28 69 6e 74 29 28 69 6e 74 70 74 72 5f 74 29 28  (int)(intptr_t)(
2df0: 58 29 29 0a 23 65 6c 73 65 20 20 20 20 20 20 20  X)).#else       
2e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e10: 20 20 20 2f 2a 20 47 65 6e 65 72 61 74 65 73 20     /* Generates 
2e20: 61 20 77 61 72 6e 69 6e 67 20 2d 20 62 75 74 20  a warning - but 
2e30: 69 74 20 61 6c 77 61 79 73 20 77 6f 72 6b 73 20  it always works 
2e40: 2a 2f 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  */.# define SQLI
2e50: 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 52 28 58 29  TE_INT_TO_PTR(X)
2e60: 20 20 28 28 76 6f 69 64 2a 29 28 58 29 29 0a 23    ((void*)(X)).#
2e70: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50   define SQLITE_P
2e80: 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28  TR_TO_INT(X)  ((
2e90: 69 6e 74 29 28 58 29 29 0a 23 65 6e 64 69 66 0a  int)(X)).#endif.
2ea0: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ./*.** The SQLIT
2eb0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 6d 61 63  E_THREADSAFE mac
2ec0: 72 6f 20 6d 75 73 74 20 62 65 20 64 65 66 69 6e  ro must be defin
2ed0: 65 64 20 61 73 20 30 2c 20 31 2c 20 6f 72 20 32  ed as 0, 1, or 2
2ee0: 2e 0a 2a 2a 20 30 20 6d 65 61 6e 73 20 6d 75 74  ..** 0 means mut
2ef0: 65 78 65 73 20 61 72 65 20 70 65 72 6d 61 6e 65  exes are permane
2f00: 6e 74 6c 79 20 64 69 73 61 62 6c 65 20 61 6e 64  ntly disable and
2f10: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 73 20   the library is 
2f20: 6e 65 76 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  never.** threads
2f30: 61 66 65 2e 20 20 31 20 6d 65 61 6e 73 20 74 68  afe.  1 means th
2f40: 65 20 6c 69 62 72 61 72 79 20 69 73 20 73 65 72  e library is ser
2f50: 69 61 6c 69 7a 65 64 20 77 68 69 63 68 20 69 73  ialized which is
2f60: 20 74 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20   the highest.** 
2f70: 6c 65 76 65 6c 20 6f 66 20 74 68 72 65 61 64 73  level of threads
2f80: 61 66 65 74 79 2e 20 20 32 20 6d 65 61 6e 73 20  afety.  2 means 
2f90: 74 68 65 20 6c 69 62 61 72 79 20 69 73 20 6d 75  the libary is mu
2fa0: 6c 74 69 74 68 72 65 61 64 65 64 20 2d 20 6d 75  ltithreaded - mu
2fb0: 6c 74 69 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64  ltiple.** thread
2fc0: 73 20 63 61 6e 20 75 73 65 20 53 51 4c 69 74 65  s can use SQLite
2fd0: 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
2fe0: 77 6f 20 74 68 72 65 61 64 73 20 74 72 79 20 74  wo threads try t
2ff0: 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
3000: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
3010: 63 74 69 6f 6e 20 61 74 20 74 68 65 20 73 61 6d  ction at the sam
3020: 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c  e time..**.** Ol
3030: 64 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  der versions of 
3040: 53 51 4c 69 74 65 20 75 73 65 64 20 61 6e 20 6f  SQLite used an o
3050: 70 74 69 6f 6e 61 6c 20 54 48 52 45 41 44 53 41  ptional THREADSA
3060: 46 45 20 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20  FE macro..** We 
3070: 73 75 70 70 6f 72 74 20 74 68 61 74 20 66 6f 72  support that for
3080: 20 6c 65 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20   legacy..*/.#if 
3090: 21 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f  !defined(SQLITE_
30a0: 54 48 52 45 41 44 53 41 46 45 29 0a 23 69 66 20  THREADSAFE).#if 
30b0: 64 65 66 69 6e 65 64 28 54 48 52 45 41 44 53 41  defined(THREADSA
30c0: 46 45 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  FE).# define SQL
30d0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 54  ITE_THREADSAFE T
30e0: 48 52 45 41 44 53 41 46 45 0a 23 65 6c 73 65 0a  HREADSAFE.#else.
30f0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
3100: 54 48 52 45 41 44 53 41 46 45 20 31 20 2f 2a 20  THREADSAFE 1 /* 
3110: 49 4d 50 3a 20 52 2d 30 37 32 37 32 2d 32 32 33  IMP: R-07272-223
3120: 30 39 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e  09 */.#endif.#en
3130: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 50 6f 77 65 72  dif../*.** Power
3140: 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 20 69  safe overwrite i
3150: 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
3160: 20 20 42 75 74 20 63 61 6e 20 62 65 20 74 75 72    But can be tur
3170: 6e 65 64 20 6f 66 66 20 75 73 69 6e 67 0a 2a 2a  ned off using.**
3180: 20 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 50 4f   the -DSQLITE_PO
3190: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
31a0: 45 3d 30 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  E=0 command-line
31b0: 20 6f 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e   option..*/.#ifn
31c0: 64 65 66 20 53 51 4c 49 54 45 5f 50 4f 57 45 52  def SQLITE_POWER
31d0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 0a 23  SAFE_OVERWRITE.#
31e0: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50   define SQLITE_P
31f0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
3200: 54 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  TE 1.#endif../*.
3210: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45  ** The SQLITE_DE
3220: 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 20  FAULT_MEMSTATUS 
3230: 6d 61 63 72 6f 20 6d 75 73 74 20 62 65 20 64 65  macro must be de
3240: 66 69 6e 65 64 20 61 73 20 65 69 74 68 65 72 20  fined as either 
3250: 30 20 6f 72 20 31 2e 0a 2a 2a 20 49 74 20 64 65  0 or 1..** It de
3260: 74 65 72 6d 69 6e 65 73 20 77 68 65 74 68 65 72  termines whether
3270: 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 65 61 74   or not the feat
3280: 75 72 65 73 20 72 65 6c 61 74 65 64 20 74 6f 20  ures related to 
3290: 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
32a0: 47 5f 4d 45 4d 53 54 41 54 55 53 20 61 72 65 20  G_MEMSTATUS are 
32b0: 61 76 61 69 6c 61 62 6c 65 20 62 79 20 64 65 66  available by def
32c0: 61 75 6c 74 20 6f 72 20 6e 6f 74 2e 20 54 68 69  ault or not. Thi
32d0: 73 20 76 61 6c 75 65 20 63 61 6e 0a 2a 2a 20 62  s value can.** b
32e0: 65 20 6f 76 65 72 72 69 64 64 65 6e 20 61 74 20  e overridden at 
32f0: 72 75 6e 74 69 6d 65 20 75 73 69 6e 67 20 74 68  runtime using th
3300: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
3310: 28 29 20 41 50 49 2e 0a 2a 2f 0a 23 69 66 20 21  () API..*/.#if !
3320: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44  defined(SQLITE_D
3330: 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
3340: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  ).# define SQLIT
3350: 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
3360: 54 55 53 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a  TUS 1.#endif../*
3370: 0a 2a 2a 20 45 78 61 63 74 6c 79 20 6f 6e 65 20  .** Exactly one 
3380: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
3390: 20 6d 61 63 72 6f 73 20 6d 75 73 74 20 62 65 20   macros must be 
33a0: 64 65 66 69 6e 65 64 20 69 6e 20 6f 72 64 65 72  defined in order
33b0: 20 74 6f 0a 2a 2a 20 73 70 65 63 69 66 79 20 77   to.** specify w
33c0: 68 69 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  hich memory allo
33d0: 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
33e0: 20 74 6f 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 20   to use..**.**  
33f0: 20 20 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d     SQLITE_SYSTEM
3400: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20  _MALLOC         
3410: 20 2f 2f 20 55 73 65 20 6e 6f 72 6d 61 6c 20 73   // Use normal s
3420: 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a  ystem malloc().*
3430: 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 57 49 4e  *     SQLITE_WIN
3440: 33 32 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  32_MALLOC       
3450: 20 20 20 20 2f 2f 20 55 73 65 20 57 69 6e 33 32      // Use Win32
3460: 20 6e 61 74 69 76 65 20 68 65 61 70 20 41 50 49   native heap API
3470: 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4d  .**     SQLITE_M
3480: 45 4d 44 45 42 55 47 20 20 20 20 20 20 20 20 20  EMDEBUG         
3490: 20 20 20 20 20 20 2f 2f 20 44 65 62 75 67 67 69        // Debuggi
34a0: 6e 67 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 79  ng version of sy
34b0: 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a  stem malloc().**
34c0: 0a 2a 2a 20 4f 6e 20 57 69 6e 64 6f 77 73 2c 20  .** On Windows, 
34d0: 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 57 49  if the SQLITE_WI
34e0: 4e 33 32 5f 4d 41 4c 4c 4f 43 5f 56 41 4c 49 44  N32_MALLOC_VALID
34f0: 41 54 45 20 6d 61 63 72 6f 20 69 73 20 64 65 66  ATE macro is def
3500: 69 6e 65 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ined and the.** 
3510: 61 73 73 65 72 74 28 29 20 6d 61 63 72 6f 20 69  assert() macro i
3520: 73 20 65 6e 61 62 6c 65 64 2c 20 65 61 63 68 20  s enabled, each 
3530: 63 61 6c 6c 20 69 6e 74 6f 20 74 68 65 20 57 69  call into the Wi
3540: 6e 33 32 20 6e 61 74 69 76 65 20 68 65 61 70 20  n32 native heap 
3550: 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 77 69 6c  subsystem.** wil
3560: 6c 20 63 61 75 73 65 20 48 65 61 70 56 61 6c 69  l cause HeapVali
3570: 64 61 74 65 20 74 6f 20 62 65 20 63 61 6c 6c 65  date to be calle
3580: 64 2e 20 20 49 66 20 68 65 61 70 20 76 61 6c 69  d.  If heap vali
3590: 64 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 61  dation should fa
35a0: 69 6c 2c 20 61 6e 0a 2a 2a 20 61 73 73 65 72 74  il, an.** assert
35b0: 69 6f 6e 20 77 69 6c 6c 20 62 65 20 74 72 69 67  ion will be trig
35c0: 67 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 28 48 69  gered..**.** (Hi
35d0: 73 74 6f 72 69 63 61 6c 20 6e 6f 74 65 3a 20 20  storical note:  
35e0: 54 68 65 72 65 20 75 73 65 64 20 74 6f 20 62 65  There used to be
35f0: 20 73 65 76 65 72 61 6c 20 6f 74 68 65 72 20 6f   several other o
3600: 70 74 69 6f 6e 73 2c 20 62 75 74 20 77 65 27 76  ptions, but we'v
3610: 65 0a 2a 2a 20 70 61 72 65 64 20 69 74 20 64 6f  e.** pared it do
3620: 77 6e 20 74 6f 20 6a 75 73 74 20 74 68 65 73 65  wn to just these
3630: 20 74 68 72 65 65 2e 29 0a 2a 2a 0a 2a 2a 20 49   three.).**.** I
3640: 66 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 61 62  f none of the ab
3650: 6f 76 65 20 61 72 65 20 64 65 66 69 6e 65 64 2c  ove are defined,
3660: 20 74 68 65 6e 20 73 65 74 20 53 51 4c 49 54 45   then set SQLITE
3670: 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 61  _SYSTEM_MALLOC a
3680: 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  s.** the default
3690: 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64  ..*/.#if defined
36a0: 28 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d  (SQLITE_SYSTEM_M
36b0: 41 4c 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28 53  ALLOC)+defined(S
36c0: 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c  QLITE_WIN32_MALL
36d0: 4f 43 29 2b 64 65 66 69 6e 65 64 28 53 51 4c 49  OC)+defined(SQLI
36e0: 54 45 5f 4d 45 4d 44 45 42 55 47 29 3e 31 0a 23  TE_MEMDEBUG)>1.#
36f0: 20 65 72 72 6f 72 20 22 41 74 20 6d 6f 73 74 20   error "At most 
3700: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
3710: 77 69 6e 67 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  wing compile-tim
3720: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
3730: 6f 70 74 69 6f 6e 73 5c 0a 20 69 73 20 61 6c 6c  options\. is all
3740: 6f 77 73 3a 20 53 51 4c 49 54 45 5f 53 59 53 54  ows: SQLITE_SYST
3750: 45 4d 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49 54  EM_MALLOC, SQLIT
3760: 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 2c 20  E_WIN32_MALLOC, 
3770: 53 51 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47 22  SQLITE_MEMDEBUG"
3780: 0a 23 65 6e 64 69 66 0a 23 69 66 20 64 65 66 69  .#endif.#if defi
3790: 6e 65 64 28 53 51 4c 49 54 45 5f 53 59 53 54 45  ned(SQLITE_SYSTE
37a0: 4d 5f 4d 41 4c 4c 4f 43 29 2b 64 65 66 69 6e 65  M_MALLOC)+define
37b0: 64 28 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d  d(SQLITE_WIN32_M
37c0: 41 4c 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28 53  ALLOC)+defined(S
37d0: 51 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 3d  QLITE_MEMDEBUG)=
37e0: 3d 30 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  =0.# define SQLI
37f0: 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43  TE_SYSTEM_MALLOC
3800: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a   1.#endif../*.**
3810: 20 49 66 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f   If SQLITE_MALLO
3820: 43 5f 53 4f 46 54 5f 4c 49 4d 49 54 20 69 73 20  C_SOFT_LIMIT is 
3830: 6e 6f 74 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74  not zero, then t
3840: 72 79 20 74 6f 20 6b 65 65 70 20 74 68 65 0a 2a  ry to keep the.*
3850: 2a 20 73 69 7a 65 73 20 6f 66 20 6d 65 6d 6f 72  * sizes of memor
3860: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 62 65  y allocations be
3870: 6c 6f 77 20 74 68 69 73 20 76 61 6c 75 65 20 77  low this value w
3880: 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  here possible..*
3890: 2f 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28 53  /.#if !defined(S
38a0: 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46  QLITE_MALLOC_SOF
38b0: 54 5f 4c 49 4d 49 54 29 0a 23 20 64 65 66 69 6e  T_LIMIT).# defin
38c0: 65 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f  e SQLITE_MALLOC_
38d0: 53 4f 46 54 5f 4c 49 4d 49 54 20 31 30 32 34 0a  SOFT_LIMIT 1024.
38e0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 57 65  #endif../*.** We
38f0: 20 6e 65 65 64 20 74 6f 20 64 65 66 69 6e 65 20   need to define 
3900: 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 61 73  _XOPEN_SOURCE as
3910: 20 66 6f 6c 6c 6f 77 73 20 69 6e 20 6f 72 64 65   follows in orde
3920: 72 20 74 6f 20 65 6e 61 62 6c 65 0a 2a 2a 20 72  r to enable.** r
3930: 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 65 73  ecursive mutexes
3940: 20 6f 6e 20 6d 6f 73 74 20 55 6e 69 78 20 73 79   on most Unix sy
3950: 73 74 65 6d 73 2e 20 20 42 75 74 20 4d 61 63 20  stems.  But Mac 
3960: 4f 53 20 58 20 69 73 20 64 69 66 66 65 72 65 6e  OS X is differen
3970: 74 2e 0a 2a 2a 20 54 68 65 20 5f 58 4f 50 45 4e  t..** The _XOPEN
3980: 5f 53 4f 55 52 43 45 20 64 65 66 69 6e 65 20 63  _SOURCE define c
3990: 61 75 73 65 73 20 70 72 6f 62 6c 65 6d 73 20 66  auses problems f
39a0: 6f 72 20 4d 61 63 20 4f 53 20 58 20 77 65 20 61  or Mac OS X we a
39b0: 72 65 20 74 6f 6c 64 2c 0a 2a 2a 20 73 6f 20 69  re told,.** so i
39c0: 74 20 69 73 20 6f 6d 69 74 74 65 64 20 74 68 65  t is omitted the
39d0: 72 65 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  re.  See ticket 
39e0: 23 32 36 37 33 2e 0a 2a 2a 0a 2a 2a 20 4c 61 74  #2673..**.** Lat
39f0: 65 72 20 77 65 20 6c 65 61 72 6e 20 74 68 61 74  er we learn that
3a00: 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 69   _XOPEN_SOURCE i
3a10: 73 20 70 6f 6f 72 6c 79 20 6f 72 20 69 6e 63 6f  s poorly or inco
3a20: 72 72 65 63 74 6c 79 0a 2a 2a 20 69 6d 70 6c 65  rrectly.** imple
3a30: 6d 65 6e 74 65 64 20 6f 6e 20 73 6f 6d 65 20 73  mented on some s
3a40: 79 73 74 65 6d 73 2e 20 20 53 6f 20 77 65 20 61  ystems.  So we a
3a50: 76 6f 69 64 20 64 65 66 69 6e 69 6e 67 20 69 74  void defining it
3a60: 20 61 74 20 61 6c 6c 0a 2a 2a 20 69 66 20 69 74   at all.** if it
3a70: 20 69 73 20 61 6c 72 65 61 64 79 20 64 65 66 69   is already defi
3a80: 6e 65 64 20 6f 72 20 69 66 20 69 74 20 69 73 20  ned or if it is 
3a90: 75 6e 6e 65 65 64 65 64 20 62 65 63 61 75 73 65  unneeded because
3aa0: 20 77 65 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 64   we are.** not d
3ab0: 6f 69 6e 67 20 61 20 74 68 72 65 61 64 73 61 66  oing a threadsaf
3ac0: 65 20 62 75 69 6c 64 2e 20 20 54 69 63 6b 65 74  e build.  Ticket
3ad0: 20 23 32 36 38 31 2e 0a 2a 2a 0a 2a 2a 20 53 65   #2681..**.** Se
3ae0: 65 20 61 6c 73 6f 20 74 69 63 6b 65 74 20 23 32  e also ticket #2
3af0: 37 34 31 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66  741..*/.#if !def
3b00: 69 6e 65 64 28 5f 58 4f 50 45 4e 5f 53 4f 55 52  ined(_XOPEN_SOUR
3b10: 43 45 29 20 26 26 20 21 64 65 66 69 6e 65 64 28  CE) && !defined(
3b20: 5f 5f 44 41 52 57 49 4e 5f 5f 29 20 26 26 20 21  __DARWIN__) && !
3b30: 64 65 66 69 6e 65 64 28 5f 5f 41 50 50 4c 45 5f  defined(__APPLE_
3b40: 5f 29 20 26 26 20 53 51 4c 49 54 45 5f 54 48 52  _) && SQLITE_THR
3b50: 45 41 44 53 41 46 45 0a 23 20 20 64 65 66 69 6e  EADSAFE.#  defin
3b60: 65 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20  e _XOPEN_SOURCE 
3b70: 35 30 30 20 20 2f 2a 20 4e 65 65 64 65 64 20 74  500  /* Needed t
3b80: 6f 20 65 6e 61 62 6c 65 20 70 74 68 72 65 61 64  o enable pthread
3b90: 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
3ba0: 65 73 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a  es */.#endif../*
3bb0: 0a 2a 2a 20 54 68 65 20 54 43 4c 20 68 65 61 64  .** The TCL head
3bc0: 65 72 73 20 61 72 65 20 6f 6e 6c 79 20 6e 65 65  ers are only nee
3bd0: 64 65 64 20 77 68 65 6e 20 63 6f 6d 70 69 6c 69  ded when compili
3be0: 6e 67 20 74 68 65 20 54 43 4c 20 62 69 6e 64 69  ng the TCL bindi
3bf0: 6e 67 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69  ngs..*/.#if defi
3c00: 6e 65 64 28 53 51 4c 49 54 45 5f 54 43 4c 29 20  ned(SQLITE_TCL) 
3c10: 7c 7c 20 64 65 66 69 6e 65 64 28 54 43 4c 53 48  || defined(TCLSH
3c20: 29 0a 23 20 69 6e 63 6c 75 64 65 20 3c 74 63 6c  ).# include <tcl
3c30: 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .h>.#endif../*.*
3c40: 2a 20 4d 61 6e 79 20 70 65 6f 70 6c 65 20 61 72  * Many people ar
3c50: 65 20 66 61 69 6c 69 6e 67 20 74 6f 20 73 65 74  e failing to set
3c60: 20 2d 44 4e 44 45 42 55 47 3d 31 20 77 68 65 6e   -DNDEBUG=1 when
3c70: 20 63 6f 6d 70 69 6c 69 6e 67 20 53 51 4c 69 74   compiling SQLit
3c80: 65 2e 0a 2a 2a 20 53 65 74 74 69 6e 67 20 4e 44  e..** Setting ND
3c90: 45 42 55 47 20 6d 61 6b 65 73 20 74 68 65 20 63  EBUG makes the c
3ca0: 6f 64 65 20 73 6d 61 6c 6c 65 72 20 61 6e 64 20  ode smaller and 
3cb0: 72 75 6e 20 66 61 73 74 65 72 2e 20 20 53 6f 20  run faster.  So 
3cc0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a  the following.**
3cd0: 20 6c 69 6e 65 73 20 61 72 65 20 61 64 64 65 64   lines are added
3ce0: 20 74 6f 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   to automaticall
3cf0: 79 20 73 65 74 20 4e 44 45 42 55 47 20 75 6e 6c  y set NDEBUG unl
3d00: 65 73 73 20 74 68 65 20 2d 44 53 51 4c 49 54 45  ess the -DSQLITE
3d10: 5f 44 45 42 55 47 3d 31 0a 2a 2a 20 6f 70 74 69  _DEBUG=1.** opti
3d20: 6f 6e 20 69 73 20 73 65 74 2e 20 20 54 68 75 73  on is set.  Thus
3d30: 20 4e 44 45 42 55 47 20 62 65 63 6f 6d 65 73 20   NDEBUG becomes 
3d40: 61 6e 20 6f 70 74 2d 69 6e 20 72 61 74 68 65 72  an opt-in rather
3d50: 20 74 68 61 6e 20 61 6e 20 6f 70 74 2d 6f 75 74   than an opt-out
3d60: 0a 2a 2a 20 66 65 61 74 75 72 65 2e 0a 2a 2f 0a  .** feature..*/.
3d70: 23 69 66 20 21 64 65 66 69 6e 65 64 28 4e 44 45  #if !defined(NDE
3d80: 42 55 47 29 20 26 26 20 21 64 65 66 69 6e 65 64  BUG) && !defined
3d90: 28 53 51 4c 49 54 45 5f 44 45 42 55 47 29 20 0a  (SQLITE_DEBUG) .
3da0: 23 20 64 65 66 69 6e 65 20 4e 44 45 42 55 47 20  # define NDEBUG 
3db0: 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  1.#endif../*.** 
3dc0: 54 68 65 20 74 65 73 74 63 61 73 65 28 29 20 6d  The testcase() m
3dd0: 61 63 72 6f 20 69 73 20 75 73 65 64 20 74 6f 20  acro is used to 
3de0: 61 69 64 20 69 6e 20 63 6f 76 65 72 61 67 65 20  aid in coverage 
3df0: 74 65 73 74 69 6e 67 2e 20 20 57 68 65 6e 20 0a  testing.  When .
3e00: 2a 2a 20 64 6f 69 6e 67 20 63 6f 76 65 72 61 67  ** doing coverag
3e10: 65 20 74 65 73 74 69 6e 67 2c 20 74 68 65 20 63  e testing, the c
3e20: 6f 6e 64 69 74 69 6f 6e 20 69 6e 73 69 64 65 20  ondition inside 
3e30: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
3e40: 2a 2a 20 74 65 73 74 63 61 73 65 28 29 20 6d 75  ** testcase() mu
3e50: 73 74 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  st be evaluated 
3e60: 62 6f 74 68 20 74 72 75 65 20 61 6e 64 20 66 61  both true and fa
3e70: 6c 73 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  lse in order to.
3e80: 2a 2a 20 67 65 74 20 66 75 6c 6c 20 62 72 61 6e  ** get full bran
3e90: 63 68 20 63 6f 76 65 72 61 67 65 2e 20 20 54 68  ch coverage.  Th
3ea0: 65 20 74 65 73 74 63 61 73 65 28 29 20 6d 61 63  e testcase() mac
3eb0: 72 6f 20 69 73 20 69 6e 73 65 72 74 65 64 0a 2a  ro is inserted.*
3ec0: 2a 20 74 6f 20 68 65 6c 70 20 65 6e 73 75 72 65  * to help ensure
3ed0: 20 61 64 65 71 75 61 74 65 20 74 65 73 74 20 63   adequate test c
3ee0: 6f 76 65 72 61 67 65 20 69 6e 20 70 6c 61 63 65  overage in place
3ef0: 73 20 77 68 65 72 65 20 73 69 6d 70 6c 65 0a 2a  s where simple.*
3f00: 2a 20 63 6f 6e 64 69 74 69 6f 6e 2f 64 65 63 69  * condition/deci
3f10: 73 69 6f 6e 20 63 6f 76 65 72 61 67 65 20 69 73  sion coverage is
3f20: 20 69 6e 61 64 65 71 75 61 74 65 2e 20 20 46 6f   inadequate.  Fo
3f30: 72 20 65 78 61 6d 70 6c 65 2c 20 74 65 73 74 63  r example, testc
3f40: 61 73 65 28 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ase().** can be 
3f50: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 73 75 72  used to make sur
3f60: 65 20 62 6f 75 6e 64 61 72 79 20 76 61 6c 75 65  e boundary value
3f70: 73 20 61 72 65 20 74 65 73 74 65 64 2e 20 20 46  s are tested.  F
3f80: 6f 72 0a 2a 2a 20 62 69 74 6d 61 73 6b 20 74 65  or.** bitmask te
3f90: 73 74 73 2c 20 74 65 73 74 63 61 73 65 28 29 20  sts, testcase() 
3fa0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6d  can be used to m
3fb0: 61 6b 65 20 73 75 72 65 20 65 61 63 68 20 62 69  ake sure each bi
3fc0: 74 0a 2a 2a 20 69 73 20 73 69 67 6e 69 66 69 63  t.** is signific
3fd0: 61 6e 74 20 61 6e 64 20 75 73 65 64 20 61 74 20  ant and used at 
3fe0: 6c 65 61 73 74 20 6f 6e 63 65 2e 20 20 4f 6e 20  least once.  On 
3ff0: 73 77 69 74 63 68 20 73 74 61 74 65 6d 65 6e 74  switch statement
4000: 73 0a 2a 2a 20 77 68 65 72 65 20 6d 75 6c 74 69  s.** where multi
4010: 70 6c 65 20 63 61 73 65 73 20 67 6f 20 74 6f 20  ple cases go to 
4020: 74 68 65 20 73 61 6d 65 20 62 6c 6f 63 6b 20 6f  the same block o
4030: 66 20 63 6f 64 65 2c 20 74 65 73 74 63 61 73 65  f code, testcase
4040: 28 29 0a 2a 2a 20 63 61 6e 20 69 6e 73 75 72 65  ().** can insure
4050: 20 74 68 61 74 20 61 6c 6c 20 63 61 73 65 73 20   that all cases 
4060: 61 72 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a  are evaluated..*
4070: 2a 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  *.*/.#ifdef SQLI
4080: 54 45 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 54  TE_COVERAGE_TEST
4090: 0a 53 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20  .SQLITE_PRIVATE 
40a0: 20 20 76 6f 69 64 20 73 71 6c 69 74 65 33 43 6f    void sqlite3Co
40b0: 76 65 72 61 67 65 28 69 6e 74 29 3b 0a 23 20 64  verage(int);.# d
40c0: 65 66 69 6e 65 20 74 65 73 74 63 61 73 65 28 58  efine testcase(X
40d0: 29 20 20 69 66 28 20 58 20 29 7b 20 73 71 6c 69  )  if( X ){ sqli
40e0: 74 65 33 43 6f 76 65 72 61 67 65 28 5f 5f 4c 49  te3Coverage(__LI
40f0: 4e 45 5f 5f 29 3b 20 7d 0a 23 65 6c 73 65 0a 23  NE__); }.#else.#
4100: 20 64 65 66 69 6e 65 20 74 65 73 74 63 61 73 65   define testcase
4110: 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  (X).#endif../*.*
4120: 2a 20 54 68 65 20 54 45 53 54 4f 4e 4c 59 20 6d  * The TESTONLY m
4130: 61 63 72 6f 20 69 73 20 75 73 65 64 20 74 6f 20  acro is used to 
4140: 65 6e 63 6c 6f 73 65 20 76 61 72 69 61 62 6c 65  enclose variable
4150: 20 64 65 63 6c 61 72 61 74 69 6f 6e 73 20 6f 72   declarations or
4160: 0a 2a 2a 20 6f 74 68 65 72 20 62 69 74 73 20 6f  .** other bits o
4170: 66 20 63 6f 64 65 20 74 68 61 74 20 61 72 65 20  f code that are 
4180: 6e 65 65 64 65 64 20 74 6f 20 73 75 70 70 6f 72  needed to suppor
4190: 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 73 0a  t the arguments.
41a0: 2a 2a 20 77 69 74 68 69 6e 20 74 65 73 74 63 61  ** within testca
41b0: 73 65 28 29 20 61 6e 64 20 61 73 73 65 72 74 28  se() and assert(
41c0: 29 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 69 66  ) macros..*/.#if
41d0: 20 21 64 65 66 69 6e 65 64 28 4e 44 45 42 55 47   !defined(NDEBUG
41e0: 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 53 51 4c  ) || defined(SQL
41f0: 49 54 45 5f 43 4f 56 45 52 41 47 45 5f 54 45 53  ITE_COVERAGE_TES
4200: 54 29 0a 23 20 64 65 66 69 6e 65 20 54 45 53 54  T).# define TEST
4210: 4f 4e 4c 59 28 58 29 20 20 58 0a 23 65 6c 73 65  ONLY(X)  X.#else
4220: 0a 23 20 64 65 66 69 6e 65 20 54 45 53 54 4f 4e  .# define TESTON
4230: 4c 59 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a  LY(X).#endif../*
4240: 0a 2a 2a 20 53 6f 6d 65 74 69 6d 65 73 20 77 65  .** Sometimes we
4250: 20 6e 65 65 64 20 61 20 73 6d 61 6c 6c 20 61 6d   need a small am
4260: 6f 75 6e 74 20 6f 66 20 63 6f 64 65 20 73 75 63  ount of code suc
4270: 68 20 61 73 20 61 20 76 61 72 69 61 62 6c 65 20  h as a variable 
4280: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 0a 2a  initialization.*
4290: 2a 20 74 6f 20 73 65 74 75 70 20 66 6f 72 20 61  * to setup for a
42a0: 20 6c 61 74 65 72 20 61 73 73 65 72 74 28 29 20   later assert() 
42b0: 73 74 61 74 65 6d 65 6e 74 2e 20 20 57 65 20 64  statement.  We d
42c0: 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 69 73 20  o not want this 
42d0: 63 6f 64 65 20 74 6f 0a 2a 2a 20 61 70 70 65 61  code to.** appea
42e0: 72 20 77 68 65 6e 20 61 73 73 65 72 74 28 29 20  r when assert() 
42f0: 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68  is disabled.  Th
4300: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6d 61 63 72  e following macr
4310: 6f 20 69 73 20 74 68 65 72 65 66 6f 72 65 0a 2a  o is therefore.*
4320: 2a 20 75 73 65 64 20 74 6f 20 63 6f 6e 74 61 69  * used to contai
4330: 6e 20 74 68 61 74 20 73 65 74 75 70 20 63 6f 64  n that setup cod
4340: 65 2e 20 20 54 68 65 20 22 56 56 41 22 20 61 63  e.  The "VVA" ac
4350: 72 6f 6e 79 6d 20 73 74 61 6e 64 73 20 66 6f 72  ronym stands for
4360: 0a 2a 2a 20 22 56 65 72 69 66 69 63 61 74 69 6f  .** "Verificatio
4370: 6e 2c 20 56 61 6c 69 64 61 74 69 6f 6e 2c 20 61  n, Validation, a
4380: 6e 64 20 41 63 63 72 65 64 69 74 61 74 69 6f 6e  nd Accreditation
4390: 22 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ".  In other wor
43a0: 64 73 2c 20 74 68 65 0a 2a 2a 20 63 6f 64 65 20  ds, the.** code 
43b0: 77 69 74 68 69 6e 20 56 56 41 5f 4f 4e 4c 59 28  within VVA_ONLY(
43c0: 29 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 75 6e 20  ) will only run 
43d0: 64 75 72 69 6e 67 20 76 65 72 69 66 69 63 61 74  during verificat
43e0: 69 6f 6e 20 70 72 6f 63 65 73 73 65 73 2e 0a 2a  ion processes..*
43f0: 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45 42 55 47  /.#ifndef NDEBUG
4400: 0a 23 20 64 65 66 69 6e 65 20 56 56 41 5f 4f 4e  .# define VVA_ON
4410: 4c 59 28 58 29 20 20 58 0a 23 65 6c 73 65 0a 23  LY(X)  X.#else.#
4420: 20 64 65 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59   define VVA_ONLY
4430: 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  (X).#endif../*.*
4440: 2a 20 54 68 65 20 41 4c 57 41 59 53 20 61 6e 64  * The ALWAYS and
4450: 20 4e 45 56 45 52 20 6d 61 63 72 6f 73 20 73 75   NEVER macros su
4460: 72 72 6f 75 6e 64 20 62 6f 6f 6c 65 61 6e 20 65  rround boolean e
4470: 78 70 72 65 73 73 69 6f 6e 73 20 77 68 69 63 68  xpressions which
4480: 20 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65   .** are intende
4490: 64 20 74 6f 20 61 6c 77 61 79 73 20 62 65 20 74  d to always be t
44a0: 72 75 65 20 6f 72 20 66 61 6c 73 65 2c 20 72 65  rue or false, re
44b0: 73 70 65 63 74 69 76 65 6c 79 2e 20 20 53 75 63  spectively.  Suc
44c0: 68 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  h.** expressions
44d0: 20 63 6f 75 6c 64 20 62 65 20 6f 6d 69 74 74 65   could be omitte
44e0: 64 20 66 72 6f 6d 20 74 68 65 20 63 6f 64 65 20  d from the code 
44f0: 63 6f 6d 70 6c 65 74 65 6c 79 2e 20 20 42 75 74  completely.  But
4500: 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 69 6e 63   they.** are inc
4510: 6c 75 64 65 64 20 69 6e 20 61 20 66 65 77 20 63  luded in a few c
4520: 61 73 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  ases in order to
4530: 20 65 6e 68 61 6e 63 65 20 74 68 65 20 72 65 73   enhance the res
4540: 69 6c 69 65 6e 63 65 0a 2a 2a 20 6f 66 20 53 51  ilience.** of SQ
4550: 4c 69 74 65 20 74 6f 20 75 6e 65 78 70 65 63 74  Lite to unexpect
4560: 65 64 20 62 65 68 61 76 69 6f 72 20 2d 20 74 6f  ed behavior - to
4570: 20 6d 61 6b 65 20 74 68 65 20 63 6f 64 65 20 22   make the code "
4580: 73 65 6c 66 2d 68 65 61 6c 69 6e 67 22 0a 2a 2a  self-healing".**
4590: 20 6f 72 20 22 64 75 63 74 69 6c 65 22 20 72 61   or "ductile" ra
45a0: 74 68 65 72 20 74 68 61 6e 20 62 65 69 6e 67 20  ther than being 
45b0: 22 62 72 69 74 74 6c 65 22 20 61 6e 64 20 63 72  "brittle" and cr
45c0: 61 73 68 69 6e 67 20 61 74 20 74 68 65 20 66 69  ashing at the fi
45d0: 72 73 74 0a 2a 2a 20 68 69 6e 74 20 6f 66 20 75  rst.** hint of u
45e0: 6e 70 6c 61 6e 6e 65 64 20 62 65 68 61 76 69 6f  nplanned behavio
45f0: 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  r..**.** In othe
4600: 72 20 77 6f 72 64 73 2c 20 41 4c 57 41 59 53 20  r words, ALWAYS 
4610: 61 6e 64 20 4e 45 56 45 52 20 61 72 65 20 61 64  and NEVER are ad
4620: 64 65 64 20 66 6f 72 20 64 65 66 65 6e 73 69 76  ded for defensiv
4630: 65 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  e code..**.** Wh
4640: 65 6e 20 64 6f 69 6e 67 20 63 6f 76 65 72 61 67  en doing coverag
4650: 65 20 74 65 73 74 69 6e 67 20 41 4c 57 41 59 53  e testing ALWAYS
4660: 20 61 6e 64 20 4e 45 56 45 52 20 61 72 65 20 68   and NEVER are h
4670: 61 72 64 2d 63 6f 64 65 64 20 74 6f 0a 2a 2a 20  ard-coded to.** 
4680: 62 65 20 74 72 75 65 20 61 6e 64 20 66 61 6c 73  be true and fals
4690: 65 20 73 6f 20 74 68 61 74 20 74 68 65 20 75 6e  e so that the un
46a0: 72 65 61 63 68 61 62 6c 65 20 63 6f 64 65 20 74  reachable code t
46b0: 68 65 6e 20 73 70 65 63 69 66 79 20 77 69 6c 6c  hen specify will
46c0: 0a 2a 2a 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74  .** not be count
46d0: 65 64 20 61 73 20 75 6e 74 65 73 74 65 64 20 63  ed as untested c
46e0: 6f 64 65 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69  ode..*/.#if defi
46f0: 6e 65 64 28 53 51 4c 49 54 45 5f 43 4f 56 45 52  ned(SQLITE_COVER
4700: 41 47 45 5f 54 45 53 54 29 0a 23 20 64 65 66 69  AGE_TEST).# defi
4710: 6e 65 20 41 4c 57 41 59 53 28 58 29 20 20 20 20  ne ALWAYS(X)    
4720: 20 20 28 31 29 0a 23 20 64 65 66 69 6e 65 20 4e    (1).# define N
4730: 45 56 45 52 28 58 29 20 20 20 20 20 20 20 28 30  EVER(X)       (0
4740: 29 0a 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64  ).#elif !defined
4750: 28 4e 44 45 42 55 47 29 0a 23 20 64 65 66 69 6e  (NDEBUG).# defin
4760: 65 20 41 4c 57 41 59 53 28 58 29 20 20 20 20 20  e ALWAYS(X)     
4770: 20 28 28 58 29 3f 31 3a 28 61 73 73 65 72 74 28   ((X)?1:(assert(
4780: 30 29 2c 30 29 29 0a 23 20 64 65 66 69 6e 65 20  0),0)).# define 
4790: 4e 45 56 45 52 28 58 29 20 20 20 20 20 20 20 28  NEVER(X)       (
47a0: 28 58 29 3f 28 61 73 73 65 72 74 28 30 29 2c 31  (X)?(assert(0),1
47b0: 29 3a 30 29 0a 23 65 6c 73 65 0a 23 20 64 65 66  ):0).#else.# def
47c0: 69 6e 65 20 41 4c 57 41 59 53 28 58 29 20 20 20  ine ALWAYS(X)   
47d0: 20 20 20 28 58 29 0a 23 20 64 65 66 69 6e 65 20     (X).# define 
47e0: 4e 45 56 45 52 28 58 29 20 20 20 20 20 20 20 28  NEVER(X)       (
47f0: 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  X).#endif../*.**
4800: 20 52 65 74 75 72 6e 20 74 72 75 65 20 28 6e 6f   Return true (no
4810: 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 20 69  n-zero) if the i
4820: 6e 70 75 74 20 69 73 20 61 20 69 6e 74 65 67 65  nput is a intege
4830: 72 20 74 68 61 74 20 69 73 20 74 6f 6f 20 6c 61  r that is too la
4840: 72 67 65 0a 2a 2a 20 74 6f 20 66 69 74 20 69 6e  rge.** to fit in
4850: 20 33 32 2d 62 69 74 73 2e 20 20 54 68 69 73 20   32-bits.  This 
4860: 6d 61 63 72 6f 20 69 73 20 75 73 65 64 20 69 6e  macro is used in
4870: 73 69 64 65 20 6f 66 20 76 61 72 69 6f 75 73 20  side of various 
4880: 74 65 73 74 63 61 73 65 28 29 0a 2a 2a 20 6d 61  testcase().** ma
4890: 63 72 6f 73 20 74 6f 20 76 65 72 69 66 79 20 74  cros to verify t
48a0: 68 61 74 20 77 65 20 68 61 76 65 20 74 65 73 74  hat we have test
48b0: 65 64 20 53 51 4c 69 74 65 20 66 6f 72 20 6c 61  ed SQLite for la
48c0: 72 67 65 2d 66 69 6c 65 20 73 75 70 70 6f 72 74  rge-file support
48d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 49 53 5f  ..*/.#define IS_
48e0: 42 49 47 5f 49 4e 54 28 58 29 20 20 28 28 28 58  BIG_INT(X)  (((X
48f0: 29 26 7e 28 69 36 34 29 30 78 66 66 66 66 66 66  )&~(i64)0xffffff
4900: 66 66 29 21 3d 30 29 0a 0a 2f 2a 0a 2a 2a 20 54  ff)!=0)../*.** T
4910: 68 65 20 6d 61 63 72 6f 20 75 6e 6c 69 6b 65 6c  he macro unlikel
4920: 79 28 29 20 69 73 20 61 20 68 69 6e 74 20 74 68  y() is a hint th
4930: 61 74 20 73 75 72 72 6f 75 6e 64 73 20 61 20 62  at surrounds a b
4940: 6f 6f 6c 65 61 6e 0a 2a 2a 20 65 78 70 72 65 73  oolean.** expres
4950: 73 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73 75  sion that is usu
4960: 61 6c 6c 79 20 66 61 6c 73 65 2e 20 20 4d 61 63  ally false.  Mac
4970: 72 6f 20 6c 69 6b 65 6c 79 28 29 20 73 75 72 72  ro likely() surr
4980: 6f 75 6e 64 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65  ounds.** a boole
4990: 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 74 68  an expression th
49a0: 61 74 20 69 73 20 75 73 75 61 6c 6c 79 20 74 72  at is usually tr
49b0: 75 65 2e 20 20 47 43 43 20 69 73 20 61 62 6c 65  ue.  GCC is able
49c0: 20 74 6f 0a 2a 2a 20 75 73 65 20 74 68 65 73 65   to.** use these
49d0: 20 68 69 6e 74 73 20 74 6f 20 67 65 6e 65 72 61   hints to genera
49e0: 74 65 20 62 65 74 74 65 72 20 63 6f 64 65 2c 20  te better code, 
49f0: 73 6f 6d 65 74 69 6d 65 73 2e 0a 2a 2f 0a 23 69  sometimes..*/.#i
4a00: 66 20 64 65 66 69 6e 65 64 28 5f 5f 47 4e 55 43  f defined(__GNUC
4a10: 5f 5f 29 20 26 26 20 30 0a 23 20 64 65 66 69 6e  __) && 0.# defin
4a20: 65 20 6c 69 6b 65 6c 79 28 58 29 20 20 20 20 5f  e likely(X)    _
4a30: 5f 62 75 69 6c 74 69 6e 5f 65 78 70 65 63 74 28  _builtin_expect(
4a40: 28 58 29 2c 31 29 0a 23 20 64 65 66 69 6e 65 20  (X),1).# define 
4a50: 75 6e 6c 69 6b 65 6c 79 28 58 29 20 20 5f 5f 62  unlikely(X)  __b
4a60: 75 69 6c 74 69 6e 5f 65 78 70 65 63 74 28 28 58  uiltin_expect((X
4a70: 29 2c 30 29 0a 23 65 6c 73 65 0a 23 20 64 65 66  ),0).#else.# def
4a80: 69 6e 65 20 6c 69 6b 65 6c 79 28 58 29 20 20 20  ine likely(X)   
4a90: 20 21 21 28 58 29 0a 23 20 64 65 66 69 6e 65 20   !!(X).# define 
4aa0: 75 6e 6c 69 6b 65 6c 79 28 58 29 20 20 21 21 28  unlikely(X)  !!(
4ab0: 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 2a 2a 2a  X).#endif../****
4ac0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75  ********** Inclu
4ad0: 64 65 20 73 71 6c 69 74 65 33 2e 68 20 69 6e 20  de sqlite3.h in 
4ae0: 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71  the middle of sq
4af0: 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a  liteInt.h ******
4b00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a  *********/./****
4b10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e  ********** Begin
4b20: 20 66 69 6c 65 20 73 71 6c 69 74 65 33 2e 68 20   file sqlite3.h 
4b30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4b40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4b50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a  *********/./*.**
4b60: 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20   2001 September 
4b70: 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  15.**.** The aut
4b80: 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f  hor disclaims co
4b90: 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20  pyright to this 
4ba0: 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e  source code.  In
4bb0: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c   place of.** a l
4bc0: 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72  egal notice, her
4bd0: 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a  e is a blessing:
4be0: 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f  .**.**    May yo
4bf0: 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f  u do good and no
4c00: 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61  t evil..**    Ma
4c10: 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69  y you find forgi
4c20: 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73  veness for yours
4c30: 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20  elf and forgive 
4c40: 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61  others..**    Ma
4c50: 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65  y you share free
4c60: 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67  ly, never taking
4c70: 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67   more than you g
4c80: 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a  ive..**.********
4c90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4ca0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4cb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4cc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4cd0: 2a 0a 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72  *.** This header
4ce0: 20 66 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68   file defines th
4cf0: 65 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  e interface that
4d00: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
4d10: 61 72 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20  ary.** presents 
4d20: 74 6f 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61  to client progra
4d30: 6d 73 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63  ms.  If a C-func
4d40: 74 69 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c  tion, structure,
4d50: 20 64 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72   datatype,.** or
4d60: 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69   constant defini
4d70: 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70  tion does not ap
4d80: 70 65 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c  pear in this fil
4d90: 65 2c 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a  e, then it is.**
4da0: 20 6e 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64   not a published
4db0: 20 41 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20   API of SQLite, 
4dc0: 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  is subject to ch
4dd0: 61 6e 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20  ange without.** 
4de0: 6e 6f 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75  notice, and shou
4df0: 6c 64 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65  ld not be refere
4e00: 6e 63 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73  nced by programs
4e10: 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 65   that use SQLite
4e20: 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20  ..**.** Some of 
4e30: 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20  the definitions 
4e40: 74 68 61 74 20 61 72 65 20 69 6e 20 74 68 69 73  that are in this
4e50: 20 66 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64   file are marked
4e60: 20 61 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65   as.** "experime
4e70: 6e 74 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65  ntal".  Experime
4e80: 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  ntal interfaces 
4e90: 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77  are normally new
4ea0: 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 72 65 63  .** features rec
4eb0: 65 6e 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53  ently added to S
4ec0: 51 4c 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f  QLite.  We do no
4ed0: 74 20 61 6e 74 69 63 69 70 61 74 65 20 63 68 61  t anticipate cha
4ee0: 6e 67 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72  nges.** to exper
4ef0: 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63  imental interfac
4f00: 65 73 20 62 75 74 20 72 65 73 65 72 76 65 20 74  es but reserve t
4f10: 68 65 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65  he right to make
4f20: 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a   minor changes.*
4f30: 2a 20 69 66 20 65 78 70 65 72 69 65 6e 63 65 20  * if experience 
4f40: 66 72 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65  from use "in the
4f50: 20 77 69 6c 64 22 20 73 75 67 67 65 73 74 20 73   wild" suggest s
4f60: 75 63 68 20 63 68 61 6e 67 65 73 20 61 72 65 20  uch changes are 
4f70: 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  prudent..**.** T
4f80: 68 65 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61  he official C-la
4f90: 6e 67 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d  nguage API docum
4fa0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c  entation for SQL
4fb0: 69 74 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a  ite is derived.*
4fc0: 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20  * from comments 
4fd0: 69 6e 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54  in this file.  T
4fe0: 68 69 73 20 66 69 6c 65 20 69 73 20 74 68 65 20  his file is the 
4ff0: 61 75 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f  authoritative so
5000: 75 72 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53  urce.** on how S
5010: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
5020: 20 61 72 65 20 73 75 70 70 6f 73 65 20 74 6f 20   are suppose to 
5030: 6f 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  operate..**.** T
5040: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20  he name of this 
5050: 66 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69  file under confi
5060: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
5070: 65 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68  ent is "sqlite.h
5080: 2e 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b  .in"..** The mak
5090: 65 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65  efile makes some
50a0: 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74   minor changes t
50b0: 6f 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63  o this file (suc
50c0: 68 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a  h as inserting.*
50d0: 2a 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75  * the version nu
50e0: 6d 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65  mber) and change
50f0: 73 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73  s its name to "s
5100: 71 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20  qlite3.h" as.** 
5110: 70 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c  part of the buil
5120: 64 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69  d process..*/.#i
5130: 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48  fndef _SQLITE3_H
5140: 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54  _.#define _SQLIT
5150: 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c  E3_H_.#include <
5160: 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a  stdarg.h>     /*
5170: 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 20   Needed for the 
5180: 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61  definition of va
5190: 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  _list */../*.** 
51a0: 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e  Make sure we can
51b0: 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66   call this stuff
51c0: 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69   from C++..*/.#i
51d0: 66 20 30 0a 65 78 74 65 72 6e 20 22 43 22 20 7b  f 0.extern "C" {
51e0: 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20  .#endif.../*.** 
51f0: 41 64 64 20 74 68 65 20 61 62 69 6c 69 74 79 20  Add the ability 
5200: 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65 78 74  to override 'ext
5210: 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ern'.*/.#ifndef 
5220: 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20  SQLITE_EXTERN.# 
5230: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
5240: 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64  TERN extern.#end
5250: 69 66 0a 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  if..#ifndef SQLI
5260: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
5270: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
5280: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20  f.../*.** These 
5290: 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 72 65  no-op macros are
52a0: 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f   used in front o
52b0: 66 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  f interfaces to 
52c0: 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e  mark those.** in
52d0: 74 65 72 66 61 63 65 73 20 61 73 20 65 69 74 68  terfaces as eith
52e0: 65 72 20 64 65 70 72 65 63 61 74 65 64 20 6f 72  er deprecated or
52f0: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20   experimental.  
5300: 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  New applications
5310: 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75  .** should not u
5320: 73 65 20 64 65 70 72 65 63 61 74 65 64 20 69 6e  se deprecated in
5330: 74 65 72 66 61 63 65 73 20 2d 20 74 68 65 79 20  terfaces - they 
5340: 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f 72 20  are support for 
5350: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
5360: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
5370: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72    Application wr
5380: 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20  iters should be 
5390: 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78  aware that.** ex
53a0: 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72  perimental inter
53b0: 66 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63  faces are subjec
53c0: 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70  t to change in p
53d0: 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a  oint releases..*
53e0: 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f  *.** These macro
53f0: 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76  s used to resolv
5400: 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e  e to various kin
5410: 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d  ds of compiler m
5420: 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75  agic that.** wou
5430: 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e  ld generate warn
5440: 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65  ing messages whe
5450: 6e 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64  n they were used
5460: 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63  .  But that.** c
5470: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e  ompiler magic en
5480: 64 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e  ded up generatin
5490: 67 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20  g such a flurry 
54a0: 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a  of bug reports.*
54b0: 2a 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74  * that we have t
54c0: 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20  aken it all out 
54d0: 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f  and gone back to
54e0: 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a   using simple.**
54f0: 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f   noop macros..*/
5500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5510: 44 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69  DEPRECATED.#defi
5520: 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49  ne SQLITE_EXPERI
5530: 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e  MENTAL../*.** En
5540: 73 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f  sure these symbo
5550: 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69  ls were not defi
5560: 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76  ned by some prev
5570: 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65  ious header file
5580: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
5590: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64  TE_VERSION.# und
55a0: 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ef SQLITE_VERSIO
55b0: 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20  N.#endif.#ifdef 
55c0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
55d0: 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51  UMBER.# undef SQ
55e0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
55f0: 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  BER.#endif../*.*
5600: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
5610: 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  ile-Time Library
5620: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
5630: 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51  .**.** ^(The [SQ
5640: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20  LITE_VERSION] C 
5650: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
5660: 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ro in the sqlite
5670: 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76  3.h header.** ev
5680: 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72  aluates to a str
5690: 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74  ing literal that
56a0: 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76   is the SQLite v
56b0: 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a  ersion in the.**
56c0: 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20   format "X.Y.Z" 
56d0: 77 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d  where X is the m
56e0: 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ajor version num
56f0: 62 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f  ber (always 3 fo
5700: 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e  r.** SQLite3) an
5710: 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72  d Y is the minor
5720: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
5730: 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c  and Z is the rel
5740: 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a  ease number.)^.*
5750: 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f  * ^(The [SQLITE_
5760: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20  VERSION_NUMBER] 
5770: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
5780: 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f  acro resolves to
5790: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77   an integer.** w
57a0: 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58  ith the value (X
57b0: 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30  *1000000 + Y*100
57c0: 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20  0 + Z) where X, 
57d0: 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65  Y, and Z are the
57e0: 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73   same.** numbers
57f0: 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45   used in [SQLITE
5800: 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20  _VERSION].)^.** 
5810: 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  The SQLITE_VERSI
5820: 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e  ON_NUMBER for an
5830: 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20  y given release 
5840: 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  of SQLite will a
5850: 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72  lso.** be larger
5860: 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73   than the releas
5870: 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20  e from which it 
5880: 69 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74  is derived.  Eit
5890: 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65  her Y will.** be
58a0: 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61   held constant a
58b0: 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63  nd Z will be inc
58c0: 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65  remented or else
58d0: 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65   Y will be incre
58e0: 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20  mented.** and Z 
58f0: 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f  will be reset to
5900: 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e   zero..**.** Sin
5910: 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  ce version 3.6.1
5920: 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  8, SQLite source
5930: 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73   code has been s
5940: 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  tored in the.** 
5950: 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f  <a href="http://
5960: 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f  www.fossil-scm.o
5970: 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66  rg/">Fossil conf
5980: 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65  iguration manage
5990: 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f  ment.** system</
59a0: 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  a>.  ^The SQLITE
59b0: 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f  _SOURCE_ID macro
59c0: 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a   evaluates to.**
59d0: 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
59e0: 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61 72  identifies a par
59f0: 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e  ticular check-in
5a00: 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69   of SQLite.** wi
5a10: 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75  thin its configu
5a20: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e  ration managemen
5a30: 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20  t system.  ^The 
5a40: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
5a50: 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
5a60: 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e 64  ins the date and
5a70: 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65   time of the che
5a80: 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20  ck-in (UTC) and 
5a90: 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20  an SHA1.** hash 
5aa0: 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f  of the entire so
5ab0: 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a  urce tree..**.**
5ac0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
5ad0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
5ae0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ],.** [sqlite3_l
5af0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
5b00: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f  ()], [sqlite3_so
5b10: 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73  urceid()],.** [s
5b20: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d  qlite_version()]
5b30: 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75   and [sqlite_sou
5b40: 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64  rce_id()]..*/.#d
5b50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
5b60: 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33 2e 37  SION        "3.7
5b70: 2e 31 32 2e 31 22 0a 23 64 65 66 69 6e 65 20 53  .12.1".#define S
5b80: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
5b90: 4d 42 45 52 20 33 30 30 37 30 31 32 0a 23 64 65  MBER 3007012.#de
5ba0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  fine SQLITE_SOUR
5bb0: 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 32  CE_ID      "2012
5bc0: 2d 30 35 2d 32 32 20 30 32 3a 34 35 3a 35 33 20  -05-22 02:45:53 
5bd0: 36 64 33 32 36 64 34 34 66 64 31 64 36 32 36 61  6d326d44fd1d626a
5be0: 61 65 30 65 38 34 35 36 65 35 66 61 32 30 34 39  ae0e8456e5fa2049
5bf0: 66 31 63 65 30 37 38 39 22 0a 0a 2f 2a 0a 2a 2a  f1ce0789"../*.**
5c00: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
5c10: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
5c20: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
5c30: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
5c40: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
5c50: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
5c60: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
5c70: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
5c80: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
5c90: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
5ca0: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
5cb0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
5cc0: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
5cd0: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
5ce0: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
5cf0: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
5d00: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
5d10: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
5d20: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
5d30: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
5d40: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
5d50: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
5d60: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
5d70: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
5d80: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
5d90: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
5da0: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
5db0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
5dc0: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
5dd0: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
5de0: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
5df0: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
5e00: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
5e10: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
5e20: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
5e30: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
5e40: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
5e50: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
5e60: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
5e70: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
5e80: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
5e90: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
5ea0: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
5eb0: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
5ec0: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
5ed0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
5ee0: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
5ef0: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
5f00: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
5f10: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
5f20: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
5f30: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
5f40: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
5f50: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
5f60: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
5f70: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
5f80: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
5f90: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
5fa0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
5fb0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
5fc0: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
5fd0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
5fe0: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
5ff0: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
6000: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
6010: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
6020: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
6030: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
6040: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
6050: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
6060: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
6070: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
6080: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
6090: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
60a0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
60b0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
60c0: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
60d0: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
60e0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
60f0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
6100: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
6110: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
6120: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
6130: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
6140: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
6150: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
6160: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
6170: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
6180: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
6190: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
61a0: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
61b0: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
61c0: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
61d0: 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  PI const char sq
61e0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20  lite3_version[] 
61f0: 3d 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  = SQLITE_VERSION
6200: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
6210: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
6220: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64  _libversion(void
6230: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
6240: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
6250: 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29  3_sourceid(void)
6260: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
6270: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
6280: 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29  ion_number(void)
6290: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
62a0: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
62b0: 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20  ary Compilation 
62c0: 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74  Options Diagnost
62d0: 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ics.**.** ^The s
62e0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
62f0: 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63  tion_used() func
6300: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f  tion returns 0 o
6310: 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69  r 1 .** indicati
6320: 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73  ng whether the s
6330: 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20  pecified option 
6340: 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a  was defined at .
6350: 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  ** compile time.
6360: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70    ^The SQLITE_ p
6370: 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69  refix may be omi
6380: 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a  tted from the .*
6390: 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61  * option name pa
63a0: 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ssed to sqlite3_
63b0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
63c0: 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54  ed().  .**.** ^T
63d0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
63e0: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66  leoption_get() f
63f0: 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69  unction allows i
6400: 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72  terating.** over
6410: 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74   the list of opt
6420: 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64  ions that were d
6430: 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c  efined at compil
6440: 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74  e time by.** ret
6450: 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20  urning the N-th 
6460: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74  compile time opt
6470: 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66  ion string.  ^If
6480: 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
6490: 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ge,.** sqlite3_c
64a0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
64b0: 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  () returns a NUL
64c0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
64d0: 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65   SQLITE_ .** pre
64e0: 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66  fix is omitted f
64f0: 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20  rom any strings 
6500: 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20  returned by .** 
6510: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
6520: 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a  ption_get()..**.
6530: 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20  ** ^Support for 
6540: 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66  the diagnostic f
6550: 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33  unctions sqlite3
6560: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
6570: 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c  sed().** and sql
6580: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
6590: 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20  on_get() may be 
65a0: 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69  omitted by speci
65b0: 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53  fying the .** [S
65c0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49  QLITE_OMIT_COMPI
65d0: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20  LEOPTION_DIAGS] 
65e0: 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c  option at compil
65f0: 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  e time..**.** Se
6600: 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63  e also: SQL func
6610: 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f  tions [sqlite_co
6620: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
6630: 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
6640: 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  te_compileoption
6650: 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20  _get()] and the 
6660: 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73  [compile_options
6670: 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66   pragma]..*/.#if
6680: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
6690: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
66a0: 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20  IAGS.SQLITE_API 
66b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
66c0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63  ileoption_used(c
66d0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e  onst char *zOptN
66e0: 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ame);.SQLITE_API
66f0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
6700: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
6710: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23  on_get(int N);.#
6720: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
6730: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
6740: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
6750: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a  y Is Threadsafe.
6760: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
6770: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
6780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
6790: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c   zero if and onl
67a0: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77  y if.** SQLite w
67b0: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
67c0: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
67d0: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68  mitted due to th
67e0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
67f0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65  EADSAFE] compile
6800: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69  -time option bei
6810: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a  ng set to 0..**.
6820: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
6830: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
6840: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
6850: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
6860: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
6870: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
6880: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
6890: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
68a0: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
68b0: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
68c0: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
68d0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
68e0: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
68f0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
6900: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
6910: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
6920: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
6930: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
6940: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
6950: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
6960: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
6970: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
6980: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
6990: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
69a0: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
69b0: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
69c0: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
69d0: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
69e0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
69f0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
6a00: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
6a10: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
6a20: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
6a30: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
6a40: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66  lt behavior is f
6a50: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65  or mutexes to be
6a60: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
6a70: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
6a80: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e  an be used by an
6a90: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
6aa0: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
6ab0: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
6ac0: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
6ad0: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
6ae0: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
6af0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
6b00: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
6b10: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
6b20: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a  DSAFE] macro..**
6b30: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
6b40: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
6b50: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  on the compile-t
6b60: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e  ime mutex settin
6b70: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  g.** of the [SQL
6b80: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
6b90: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65  flag.  If SQLite
6ba0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
6bb0: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
6bc0: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74  ADSAFE=1 or =2 t
6bd0: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
6be0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
6bf0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
6c00: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
6c10: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
6c20: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
6c30: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
6c40: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
6c50: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
6c60: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
6c70: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
6c80: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
6c90: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
6ca0: 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28 54 68 65  G_MUTEX].  ^(The
6cb0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
6cc0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
6cd0: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
6ce0: 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79  ction shows only
6cf0: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
6d00: 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20  e setting of.** 
6d10: 74 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e  thread safety, n
6d20: 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20  ot any run-time 
6d30: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20  changes to that 
6d40: 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a  setting made by.
6d50: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  ** sqlite3_confi
6d60: 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  g(). In other wo
6d70: 72 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20  rds, the return 
6d80: 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
6d90: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a  e3_threadsafe().
6da0: 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20  ** is unchanged 
6db0: 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  by calls to sqli
6dc0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a  te3_config().)^.
6dd0: 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74  **.** See the [t
6de0: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64  hreading mode] d
6df0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
6e00: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
6e10: 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49  rmation..*/.SQLI
6e20: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
6e30: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f  e3_threadsafe(vo
6e40: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
6e50: 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
6e60: 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65  onnection Handle
6e70: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
6e80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
6e90: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
6ea0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
6eb0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
6ec0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
6ed0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
6ee0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
6ef0: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
6f00: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
6f10: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
6f20: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
6f30: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
6f40: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
6f50: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
6f60: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
6f70: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
6f80: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
6f90: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
6fa0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
6fb0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
6fc0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
6fd0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
6fe0: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  is its destructo
6ff0: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  r.  There are ma
7000: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61  ny other interfa
7010: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
7020: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
7030: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
7040: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
7050: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
7060: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
7070: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
7080: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
7090: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
70a0: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
70b0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
70c0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
70d0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
70e0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
70f0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
7100: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
7110: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
7120: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
7130: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
7140: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
7150: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
7160: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
7170: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
7180: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
7190: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
71a0: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
71b0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
71c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
71d0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
71e0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
71f0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
7200: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
7210: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
7220: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
7230: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
7240: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
7250: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
7260: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
7270: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
7280: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
7290: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
72a0: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
72b0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
72c0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
72d0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
72e0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
72f0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
7300: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
7310: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
7320: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
7330: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
7340: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
7350: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
7360: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
7370: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
7380: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
7390: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
73a0: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
73b0: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
73c0: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36  gned SQLITE_INT6
73d0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69  4_TYPE sqlite_ui
73e0: 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69  nt64;.#elif defi
73f0: 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c  ned(_MSC_VER) ||
7400: 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41   defined(__BORLA
7410: 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66  NDC__).  typedef
7420: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
7430: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
7440: 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36   unsigned __int6
7450: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  4 sqlite_uint64;
7460: 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66  .#else.  typedef
7470: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
7480: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
7490: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
74a0: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
74b0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e  lite_uint64;.#en
74c0: 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69  dif.typedef sqli
74d0: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  te_int64 sqlite3
74e0: 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20  _int64;.typedef 
74f0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71  sqlite_uint64 sq
7500: 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f  lite3_uint64;../
7510: 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e  *.** If compilin
7520: 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f  g for a processo
7530: 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f  r that lacks flo
7540: 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70  ating point supp
7550: 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75  ort,.** substitu
7560: 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66  te integer for f
7570: 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a  loating-point..*
7580: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
7590: 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f  OMIT_FLOATING_PO
75a0: 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75  INT.# define dou
75b0: 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ble sqlite3_int6
75c0: 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  4.#endif../*.** 
75d0: 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e  CAPI3REF: Closin
75e0: 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e  g A Database Con
75f0: 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
7600: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
7610: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68  () routine is th
7620: 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  e destructor for
7630: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
7640: 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73  bject..** ^Calls
7650: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   to sqlite3_clos
7660: 65 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  e() return SQLIT
7670: 45 5f 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c  E_OK if the [sql
7680: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a  ite3] object is.
7690: 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  ** successfully 
76a0: 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c  destroyed and al
76b0: 6c 20 61 73 73 6f 63 69 61 74 65 64 20 72 65 73  l associated res
76c0: 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c  ources are deall
76d0: 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70  ocated..**.** Ap
76e0: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
76f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
7700: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
7710: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
7720: 65 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b  ements].** and [
7730: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
7740: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
7750: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61  [BLOB handles] a
7760: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
7770: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  * the [sqlite3] 
7780: 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20  object prior to 
7790: 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c  attempting to cl
77a0: 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20  ose the object. 
77b0: 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   ^If.** sqlite3_
77c0: 63 6c 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65  close() is calle
77d0: 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65  d on a [database
77e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
77f0: 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f  t still has.** o
7800: 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70  utstanding [prep
7810: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
7820: 20 6f 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65   or [BLOB handle
7830: 73 5d 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75  s], then it retu
7840: 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55  rns.** SQLITE_BU
7850: 53 59 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73  SY..**.** ^If [s
7860: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
7870: 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65  is invoked while
7880: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
7890: 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74  s open,.** the t
78a0: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75  ransaction is au
78b0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
78c0: 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
78d0: 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74  he C parameter t
78e0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
78f0: 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74  (C)] must be eit
7900: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f  her a NULL.** po
7910: 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c  inter or an [sql
7920: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69  ite3] object poi
7930: 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  nter obtained.**
7940: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f   from [sqlite3_o
7950: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
7960: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  _open16()], or.*
7970: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
7980: 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70  v2()], and not p
7990: 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64  reviously closed
79a0: 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  ..** ^Calling sq
79b0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69  lite3_close() wi
79c0: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
79d0: 72 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  r argument is a 
79e0: 0a 2a 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  .** harmless no-
79f0: 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  op..*/.SQLITE_AP
7a00: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  I int sqlite3_cl
7a10: 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a  ose(sqlite3 *);.
7a20: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20  ./*.** The type 
7a30: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  for a callback f
7a40: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73  unction..** This
7a50: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64   is legacy and d
7a60: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69  eprecated.  It i
7a70: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68  s included for h
7a80: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d  istorical.** com
7a90: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69  patibility and i
7aa0: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64  s not documented
7ab0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74  ..*/.typedef int
7ac0: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62   (*sqlite3_callb
7ad0: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
7ae0: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a  har**, char**);.
7af0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7b00: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20   One-Step Query 
7b10: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66  Execution Interf
7b20: 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ace.**.** The sq
7b30: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
7b40: 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76  erface is a conv
7b50: 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20  enience wrapper 
7b60: 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
7b70: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
7b80: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
7b90: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
7ba0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a  _finalize()],.**
7bb0: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20   that allows an 
7bc0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72  application to r
7bd0: 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74  un multiple stat
7be0: 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a  ements of SQL.**
7bf0: 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20   without having 
7c00: 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20  to use a lot of 
7c10: 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e  C code. .**.** ^
7c20: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
7c30: 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e  () interface run
7c40: 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55  s zero or more U
7c50: 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a  TF-8 encoded,.**
7c60: 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
7c70: 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ate SQL statemen
7c80: 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69  ts passed into i
7c90: 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c  ts 2nd argument,
7ca0: 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65  .** in the conte
7cb0: 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  xt of the [datab
7cc0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
7cd0: 70 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73  passed in as its
7ce0: 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   1st.** argument
7cf0: 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  .  ^If the callb
7d00: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  ack function of 
7d10: 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  the 3rd argument
7d20: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
7d30: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
7d40: 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  L, then it is in
7d50: 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72  voked for each r
7d60: 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d  esult row.** com
7d70: 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65  ing out of the e
7d80: 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61  valuated SQL sta
7d90: 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34  tements.  ^The 4
7da0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  th argument to.*
7db0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
7dc0: 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f   is relayed thro
7dd0: 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61  ugh to the 1st a
7de0: 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a  rgument of each.
7df0: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f  ** callback invo
7e00: 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65  cation.  ^If the
7e10: 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65   callback pointe
7e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
7e30: 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20  c().** is NULL, 
7e40: 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b  then no callback
7e50: 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64   is ever invoked
7e60: 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73   and result rows
7e70: 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e   are.** ignored.
7e80: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72  .**.** ^If an er
7e90: 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65  ror occurs while
7ea0: 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20   evaluating the 
7eb0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
7ec0: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71  assed into.** sq
7ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68  lite3_exec(), th
7ee0: 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  en execution of 
7ef0: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
7f00: 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a  ement stops and.
7f10: 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74  ** subsequent st
7f20: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69  atements are ski
7f30: 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35  pped.  ^If the 5
7f40: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
7f50: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
7f60: 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  * is not NULL th
7f70: 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73  en any error mes
7f80: 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20  sage is written 
7f90: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
7fa0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
7fb0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
7fc0: 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20  and passed back 
7fd0: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
7fe0: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f  parameter..** To
7ff0: 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65   avoid memory le
8000: 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61  aks, the applica
8010: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f  tion should invo
8020: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
8030: 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20  ()].** on error 
8040: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20  message strings 
8050: 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68  returned through
8060: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
8070: 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69  er of.** of sqli
8080: 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72  te3_exec() after
8090: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
80a0: 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20  ge string is no 
80b0: 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a  longer needed..*
80c0: 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61  * ^If the 5th pa
80d0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
80e0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74  e3_exec() is not
80f0: 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72   NULL and no err
8100: 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68  ors.** occur, th
8110: 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  en sqlite3_exec(
8120: 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74  ) sets the point
8130: 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61  er in its 5th pa
8140: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55  rameter to.** NU
8150: 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  LL before return
8160: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  ing..**.** ^If a
8170: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
8180: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
8190: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
81a0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
81b0: 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
81c0: 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77  s SQLITE_ABORT w
81d0: 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20  ithout invoking 
81e0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61  the callback aga
81f0: 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75  in and.** withou
8200: 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75  t running any su
8210: 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61  bsequent SQL sta
8220: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
8230: 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  The 2nd argument
8240: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
8250: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
8260: 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a  function is the.
8270: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  ** number of col
8280: 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
8290: 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72  lt.  ^The 3rd ar
82a0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
82b0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
82c0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
82d0: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
82e0: 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61   to strings obta
82f0: 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a  ined as if from.
8300: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
8310: 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20  mn_text()], one 
8320: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e  for each column.
8330: 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74    ^If an element
8340: 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20   of a.** result 
8350: 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  row is NULL then
8360: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
8370: 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ng string pointe
8380: 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c  r for the.** sql
8390: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
83a0: 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70  back is a NULL p
83b0: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74  ointer.  ^The 4t
83c0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
83d0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  e.** sqlite3_exe
83e0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  c() callback is 
83f0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
8400: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
8410: 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e  where each.** en
8420: 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74  try represents t
8430: 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65  he name of corre
8440: 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20  sponding result 
8450: 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e  column as obtain
8460: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
8470: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
8480: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  )]..**.** ^If th
8490: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
84a0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
84b0: 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
84c0: 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a  ter, a pointer.*
84d0: 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  * to an empty st
84e0: 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74  ring, or a point
84f0: 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  er that contains
8500: 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65   only whitespace
8510: 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20   and/or .** SQL 
8520: 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e  comments, then n
8530: 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
8540: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61   are evaluated a
8550: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  nd the database.
8560: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
8570: 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63  d..**.** Restric
8580: 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  tions:.**.** <ul
8590: 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  >.** <li> The ap
85a0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69  plication must i
85b0: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31  nsure that the 1
85c0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
85d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
85e0: 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69  *      is a vali
85f0: 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61  d and open [data
8600: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
8610: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
8620: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
8630: 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 61  ot close [databa
8640: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
8650: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
8660: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
8670: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
8680: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
8690: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
86a0: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <li>
86b0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
86c0: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
86d0: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
86e0: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
86f0: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
8700: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
8710: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
8720: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
8730: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
8740: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c  .** </ul>.*/.SQL
8750: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
8760: 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69  te3_exec(.  sqli
8770: 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20  te3*,           
8780: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8790: 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
87a0: 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
87b0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c  const char *sql,
87c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
87d0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
87e0: 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
87f0: 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c  d */.  int (*cal
8800: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
8810: 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c  ,char**,char**),
8820: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75    /* Callback fu
8830: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
8840: 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20   *,             
8850: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8860: 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72         /* 1st ar
8870: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61  gument to callba
8880: 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65  ck */.  char **e
8890: 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20  rrmsg           
88a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
88b0: 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
88c0: 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
88d0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
88e0: 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73  EF: Result Codes
88f0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
8900: 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63  LITE_OK {error c
8910: 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65  ode} {error code
8920: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
8930: 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72  {result code} {r
8940: 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a  esult codes}.**.
8950: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
8960: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
8970: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
8980: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
8990: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
89a0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
89b0: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
89c0: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
89d0: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
89e0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
89f0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
8a00: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
8a10: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
8a20: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
8a30: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
8a40: 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c   codes],.** [sql
8a50: 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
8a60: 66 6c 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45  flict()] [SQLITE
8a70: 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75  _ROLLBACK | resu
8a80: 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64  lt codes]..*/.#d
8a90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20  efine SQLITE_OK 
8aa0: 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
8ab0: 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75   Successful resu
8ac0: 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69  lt */./* beginni
8ad0: 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  ng-of-error-code
8ae0: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  s */.#define SQL
8af0: 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20  ITE_ERROR       
8b00: 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f   1   /* SQL erro
8b10: 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74  r or missing dat
8b20: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
8b30: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c   SQLITE_INTERNAL
8b40: 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65       2   /* Inte
8b50: 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72  rnal logic error
8b60: 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64   in SQLite */.#d
8b70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52  efine SQLITE_PER
8b80: 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a  M         3   /*
8b90: 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69   Access permissi
8ba0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
8bb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
8bc0: 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20  T        4   /* 
8bd0: 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  Callback routine
8be0: 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62   requested an ab
8bf0: 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ort */.#define S
8c00: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20  QLITE_BUSY      
8c10: 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61     5   /* The da
8c20: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c  tabase file is l
8c30: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
8c40: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20   SQLITE_LOCKED  
8c50: 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61       6   /* A ta
8c60: 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62  ble in the datab
8c70: 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ase is locked */
8c80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8c90: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20  NOMEM        7  
8ca0: 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66   /* A malloc() f
8cb0: 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ailed */.#define
8cc0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
8cd0: 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65       8   /* Atte
8ce0: 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72  mpt to write a r
8cf0: 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65  eadonly database
8d00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8d10: 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20  TE_INTERRUPT    
8d20: 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  9   /* Operation
8d30: 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73   terminated by s
8d40: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
8d50: 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ()*/.#define SQL
8d60: 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20  ITE_IOERR       
8d70: 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e  10   /* Some kin
8d80: 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72  d of disk I/O er
8d90: 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a  ror occurred */.
8da0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
8db0: 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20  ORRUPT     11   
8dc0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
8dd0: 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61  disk image is ma
8de0: 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69  lformed */.#defi
8df0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  ne SQLITE_NOTFOU
8e00: 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e  ND    12   /* Un
8e10: 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20  known opcode in 
8e20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8e30: 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e  trol() */.#defin
8e40: 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20  e SQLITE_FULL   
8e50: 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73       13   /* Ins
8e60: 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65  ertion failed be
8e70: 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69  cause database i
8e80: 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e  s full */.#defin
8e90: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
8ea0: 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61  N    14   /* Una
8eb0: 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ble to open the 
8ec0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
8ed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8ee0: 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20  PROTOCOL    15  
8ef0: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63   /* Database loc
8f00: 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72  k protocol error
8f10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8f20: 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31  TE_EMPTY       1
8f30: 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
8f40: 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66  is empty */.#def
8f50: 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d  ine SQLITE_SCHEM
8f60: 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54  A      17   /* T
8f70: 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
8f80: 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64  ma changed */.#d
8f90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f  efine SQLITE_TOO
8fa0: 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a  BIG      18   /*
8fb0: 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   String or BLOB 
8fc0: 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d  exceeds size lim
8fd0: 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  it */.#define SQ
8fe0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
8ff0: 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64   19   /* Abort d
9000: 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74  ue to constraint
9010: 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64   violation */.#d
9020: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
9030: 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a  MATCH    20   /*
9040: 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61   Data type misma
9050: 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tch */.#define S
9060: 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20  QLITE_MISUSE    
9070: 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72    21   /* Librar
9080: 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74  y used incorrect
9090: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
90a0: 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20  LITE_NOLFS      
90b0: 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53   22   /* Uses OS
90c0: 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75   features not su
90d0: 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20  pported on host 
90e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
90f0: 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33  E_AUTH        23
9100: 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74     /* Authorizat
9110: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
9120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52  efine SQLITE_FOR
9130: 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a  MAT      24   /*
9140: 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62   Auxiliary datab
9150: 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72  ase format error
9160: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
9170: 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32  TE_RANGE       2
9180: 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d  5   /* 2nd param
9190: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
91a0: 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67  bind out of rang
91b0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
91c0: 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20  ITE_NOTADB      
91d0: 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65  26   /* File ope
91e0: 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ned that is not 
91f0: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
9200: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9210: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
9220: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
9230: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
9240: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
9250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
9260: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
9270: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
9280: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
9290: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
92a0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
92b0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
92c0: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
92d0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
92e0: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
92f0: 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78   error code} {ex
9300: 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
9310: 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
9320: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
9330: 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65  t code} {extende
9340: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a  d result codes}.
9350: 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66  **.** In its def
9360: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
9370: 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72  on, SQLite API r
9380: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f  outines return o
9390: 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72  ne of 26 integer
93a0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c  .** [SQLITE_OK |
93b0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20   result codes]. 
93c0: 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69   However, experi
93d0: 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74  ence has shown t
93e0: 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74  hat many of.** t
93f0: 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65  hese result code
9400: 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65  s are too coarse
9410: 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20  -grained.  They 
9420: 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61  do not provide a
9430: 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d  s.** much inform
9440: 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62  ation about prob
9450: 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d  lems as programm
9460: 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20  ers might like. 
9470: 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f   In an effort to
9480: 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73  .** address this
9490: 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  , newer versions
94a0: 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73   of SQLite (vers
94b0: 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61  ion 3.3.8 and la
94c0: 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20  ter) include.** 
94d0: 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69  support for addi
94e0: 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f  tional result co
94f0: 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65  des that provide
9500: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69   more detailed i
9510: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
9520: 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20  out errors. The 
9530: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
9540: 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65  codes are enable
9550: 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a  d or disabled.**
9560: 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61   on a per databa
9570: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  se connection ba
9580: 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  sis using the.**
9590: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
95a0: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
95b0: 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f  )] API..**.** So
95c0: 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61  me of the availa
95d0: 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  ble extended res
95e0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69  ult codes are li
95f0: 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e  sted here..** On
9600: 65 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65  e may expect the
9610: 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e   number of exten
9620: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
9630: 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a   will be expand.
9640: 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53  ** over time.  S
9650: 6f 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65  oftware that use
9660: 73 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  s extended resul
9670: 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65  t codes should e
9680: 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20  xpect.** to see 
9690: 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73  new result codes
96a0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
96b0: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
96c0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
96d0: 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77  OK result code w
96e0: 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74  ill never be ext
96f0: 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20  ended.  It will 
9700: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61  always.** be exa
9710: 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64  ctly zero..*/.#d
9720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9730: 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  RR_READ         
9740: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9750: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
9760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
9770: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
9780: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
9790: 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  R | (2<<8)).#def
97a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
97b0: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  _WRITE          
97c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
97d0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
97e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
97f0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  FSYNC           
9800: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
9810: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
9820: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
9830: 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  IR_FSYNC        
9840: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
9850: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
9860: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
9870: 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20  UNCATE          
9880: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
9890: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
98a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54  SQLITE_IOERR_FST
98b0: 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28  AT             (
98c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
98d0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
98e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f  QLITE_IOERR_UNLO
98f0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
9900: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38  QLITE_IOERR | (8
9910: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
9920: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43  LITE_IOERR_RDLOC
9930: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
9940: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
9950: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9960: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
9970: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9980: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c  ITE_IOERR | (10<
9990: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
99a0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
99b0: 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  D           (SQL
99c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c  ITE_IOERR | (11<
99d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
99e0: 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20  ITE_IOERR_NOMEM 
99f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9a00: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c  ITE_IOERR | (12<
9a10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9a20: 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53  ITE_IOERR_ACCESS
9a30: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9a40: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c  ITE_IOERR | (13<
9a50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9a60: 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52  ITE_IOERR_CHECKR
9a70: 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c  ESERVEDLOCK (SQL
9a80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c  ITE_IOERR | (14<
9a90: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9aa0: 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20  ITE_IOERR_LOCK  
9ab0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9ac0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c  ITE_IOERR | (15<
9ad0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9ae0: 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20  ITE_IOERR_CLOSE 
9af0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9b00: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c  ITE_IOERR | (16<
9b10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9b20: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c  ITE_IOERR_DIR_CL
9b30: 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c  OSE         (SQL
9b40: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c  ITE_IOERR | (17<
9b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9b60: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45  ITE_IOERR_SHMOPE
9b70: 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  N           (SQL
9b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c  ITE_IOERR | (18<
9b90: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9ba0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a  ITE_IOERR_SHMSIZ
9bb0: 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  E           (SQL
9bc0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c  ITE_IOERR | (19<
9bd0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9be0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43  ITE_IOERR_SHMLOC
9bf0: 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  K           (SQL
9c00: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c  ITE_IOERR | (20<
9c10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9c20: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50  ITE_IOERR_SHMMAP
9c30: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9c40: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c  ITE_IOERR | (21<
9c50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9c60: 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20  ITE_IOERR_SEEK  
9c70: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9c80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c  ITE_IOERR | (22<
9c90: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9ca0: 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45  ITE_LOCKED_SHARE
9cb0: 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c  DCACHE      (SQL
9cc0: 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31  ITE_LOCKED |  (1
9cd0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
9ce0: 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45  LITE_BUSY_RECOVE
9cf0: 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51  RY           (SQ
9d00: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
9d10: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
9d20: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e  QLITE_CANTOPEN_N
9d30: 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53  OTEMPDIR      (S
9d40: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
9d50: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
9d60: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
9d70: 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20  _ISDIR          
9d80: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
9d90: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
9da0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
9db0: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20  T_VTAB          
9dc0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50    (SQLITE_CORRUP
9dd0: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
9de0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
9df0: 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  NLY_RECOVERY    
9e00: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
9e10: 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  NLY | (1<<8)).#d
9e20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
9e30: 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20  DONLY_CANTLOCK  
9e40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
9e50: 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a  DONLY | (2<<8)).
9e60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
9e70: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
9e80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
9e90: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 0a  BORT | (2<<8))..
9ea0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9eb0: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
9ec0: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a  pen Operations.*
9ed0: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
9ee0: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
9ef0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
9f00: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
9f10: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
9f20: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
9f30: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
9f40: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
9f50: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
9f60: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
9f70: 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ethod..*/.#defin
9f80: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  e SQLITE_OPEN_RE
9f90: 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30  ADONLY         0
9fa0: 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b  x00000001  /* Ok
9fb0: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
9fc0: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
9fd0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  e SQLITE_OPEN_RE
9fe0: 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30  ADWRITE        0
9ff0: 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b  x00000002  /* Ok
a000: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
a010: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
a020: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  e SQLITE_OPEN_CR
a030: 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30  EATE           0
a040: 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b  x00000004  /* Ok
a050: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
a060: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
a070: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45  e SQLITE_OPEN_DE
a080: 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30  LETEONCLOSE    0
a090: 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46  x00000008  /* VF
a0a0: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
a0b0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
a0c0: 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30  CLUSIVE        0
a0d0: 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46  x00000010  /* VF
a0e0: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
a0f0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55  e SQLITE_OPEN_AU
a100: 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30  TOPROXY        0
a110: 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46  x00000020  /* VF
a120: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
a130: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
a140: 49 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  I              0
a150: 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b  x00000040  /* Ok
a160: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
a170: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
a180: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
a190: 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30  IN_DB          0
a1a0: 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46  x00000100  /* VF
a1b0: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
a1c0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45  e SQLITE_OPEN_TE
a1d0: 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30  MP_DB          0
a1e0: 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46  x00000200  /* VF
a1f0: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
a200: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52  e SQLITE_OPEN_TR
a210: 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30  ANSIENT_DB     0
a220: 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46  x00000400  /* VF
a230: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
a240: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
a250: 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30  IN_JOURNAL     0
a260: 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46  x00000800  /* VF
a270: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
a280: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45  e SQLITE_OPEN_TE
a290: 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30  MP_JOURNAL     0
a2a0: 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46  x00001000  /* VF
a2b0: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
a2c0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55  e SQLITE_OPEN_SU
a2d0: 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30  BJOURNAL       0
a2e0: 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46  x00002000  /* VF
a2f0: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
a300: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
a310: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30  STER_JOURNAL   0
a320: 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46  x00004000  /* VF
a330: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
a340: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f  e SQLITE_OPEN_NO
a350: 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30  MUTEX          0
a360: 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b  x00008000  /* Ok
a370: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
a380: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
a390: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55  e SQLITE_OPEN_FU
a3a0: 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30  LLMUTEX        0
a3b0: 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b  x00010000  /* Ok
a3c0: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
a3d0: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
a3e0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  e SQLITE_OPEN_SH
a3f0: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30  AREDCACHE      0
a400: 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b  x00020000  /* Ok
a410: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
a420: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
a430: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
a440: 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30  IVATECACHE     0
a450: 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b  x00040000  /* Ok
a460: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
a470: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
a480: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41  e SQLITE_OPEN_WA
a490: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  L              0
a4a0: 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46  x00080000  /* VF
a4b0: 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65  S only */../* Re
a4c0: 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20  served:         
a4d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
a4e0: 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f  0x00F00000 */../
a4f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
a500: 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69  evice Characteri
a510: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  stics.**.** The 
a520: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
a530: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66  istics method of
a540: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
a550: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
a560: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
a570: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
a580: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20  a vector of the 
a590: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
a5a0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
a5b0: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
a5c0: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
a5d0: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
a5e0: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
a5f0: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
a600: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
a610: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
a620: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
a630: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
a640: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
a650: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
a660: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
a670: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
a680: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a690: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
a6a0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
a6b0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
a6c0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
a6d0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
a6e0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
a6f0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
a700: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
a710: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
a720: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
a730: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
a740: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
a750: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
a760: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
a770: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
a780: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
a790: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
a7a0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
a7b0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
a7c0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
a7d0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
a7e0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
a7f0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
a800: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
a810: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
a820: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
a830: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
a840: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
a850: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54   to xWrite().  T
a860: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
a870: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
a880: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61  ITE property mea
a890: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72  ns that.** after
a8a0: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e   reboot followin
a8b0: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77  g a crash or pow
a8c0: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c  er loss, the onl
a8d0: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20  y bytes in a.** 
a8e0: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77  file that were w
a8f0: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70  ritten at the ap
a900: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20  plication level 
a910: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67  might have chang
a920: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61  ed.** and that a
a930: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65  djacent bytes, e
a940: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e  ven bytes within
a950: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72   the same sector
a960: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65   are.** guarante
a970: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67  ed to be unchang
a980: 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ed..*/.#define S
a990: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
a9a0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
a9b0: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
a9c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
a9d0: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
a9e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
a9f0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
aa00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
aa10: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
aa20: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
aa30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
aa40: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
aa50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
aa60: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
aa70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
aa80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
aa90: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
aaa0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
aab0: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
aac0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
aad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
aae0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
aaf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
ab00: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
ab10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
ab20: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
ab30: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
ab40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
ab50: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
ab60: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
ab70: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
ab80: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
ab90: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
aba0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
abb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
abc0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
abd0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
abe0: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
abf0: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
ac00: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
ac10: 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69  0x00000800.#defi
ac20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
ac30: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
ac40: 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30  ITE    0x0000100
ac50: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
ac60: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20  F: File Locking 
ac70: 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  Levels.**.** SQL
ac80: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
ac90: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
aca0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
acb0: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
acc0: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
acd0: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
ace0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
acf0: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
ad00: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
ad10: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
ad20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
ad30: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
ad40: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
ad50: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
ad60: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
ad70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
ad80: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
ad90: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
ada0: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
adb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
adc0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
add0: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
ade0: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
adf0: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a  ion Type Flags.*
ae00: 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65  *.** When SQLite
ae10: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79   invokes the xSy
ae20: 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61  nc() method of a
ae30: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
ae40: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
ae50: 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69   it uses a combi
ae60: 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65  nation of.** the
ae70: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
ae80: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  s as the second 
ae90: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
aea0: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  When the SQLITE_
aeb0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c  SYNC_DATAONLY fl
aec0: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d  ag is used, it m
aed0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  eans that the.**
aee0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20   sync operation 
aef0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c  only needs to fl
af00: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73  ush data to mass
af10: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65   storage.  Inode
af20: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
af30: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73  need not be flus
af40: 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65  hed. If the lowe
af50: 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74  r four bits of t
af60: 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c  he flag.** equal
af70: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
af80: 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  MAL, that means 
af90: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73  to use normal fs
afa0: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e  ync() semantics.
afb0: 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72  .** If the lower
afc0: 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c   four bits equal
afd0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
afe0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  L, that means.**
aff0: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58   to use Mac OS X
b000: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
b010: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
b020: 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74  ()..**.** Do not
b030: 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c   confuse the SQL
b040: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
b050: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
b060: 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69  FULL flags.** wi
b070: 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73  th the [PRAGMA s
b080: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d  ynchronous]=NORM
b090: 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73  AL and [PRAGMA s
b0a0: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c  ynchronous]=FULL
b0b0: 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54  .** settings.  T
b0c0: 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20  he [synchronous 
b0d0: 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e  pragma] determin
b0e0: 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f  es when calls to
b0f0: 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46   the.** xSync VF
b100: 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61  S method occur a
b110: 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f  nd applies unifo
b120: 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  rmly across all 
b130: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68  platforms..** Th
b140: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
b150: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
b160: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20  SYNC_FULL flags 
b170: 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a  determine how.**
b180: 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69   energetic or ri
b190: 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66  gorous or forcef
b1a0: 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72  ul the sync oper
b1b0: 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a  ations are and.*
b1c0: 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69  * only make a di
b1d0: 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20  fference on Mac 
b1e0: 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61  OSX for the defa
b1f0: 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e  ult SQLite code.
b200: 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79  .** (Third-party
b210: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
b220: 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  ions might also 
b230: 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
b240: 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
b250: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
b260: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
b270: 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f  NC_FULL, but amo
b280: 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74  ng the.** operat
b290: 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69  ing systems nati
b2a0: 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62  vely supported b
b2b0: 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d  y SQLite, only M
b2c0: 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20  ac OSX.** cares 
b2d0: 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72  about the differ
b2e0: 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e  ence.).*/.#defin
b2f0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
b300: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30  RMAL        0x00
b310: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
b320: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20  TE_SYNC_FULL    
b330: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64        0x00003.#d
b340: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
b350: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20  C_DATAONLY      
b360: 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43  0x00010../*.** C
b370: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
b380: 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20  rface Open File 
b390: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20  Handle.**.** An 
b3a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
b3b0: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
b3c0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e   an open file in
b3d0: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
b3e0: 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72  3_vfs | OS inter
b3f0: 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e  face layer].  In
b400: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
b410: 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  rface.** impleme
b420: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a  ntations will.**
b430: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73   want to subclas
b440: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79  s this object by
b450: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74   appending addit
b460: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20  ional fields.** 
b470: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73  for their own us
b480: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73  e.  The pMethods
b490: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e   entry is a poin
b4a0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
b4b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
b4c0: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
b4d0: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f  fines methods fo
b4e0: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20  r performing.** 
b4f0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f  I/O operations o
b500: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e  n the open file.
b510: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
b520: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
b530: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74  sqlite3_file;.st
b540: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
b550: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75  e {.  const stru
b560: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
b570: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b  thods *pMethods;
b580: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
b590: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f   an open file */
b5a0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
b5b0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
b5c0: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d  e File Virtual M
b5d0: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a  ethods Object.**
b5e0: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
b5f0: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
b600: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
b610: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65   method populate
b620: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s an.** [sqlite3
b630: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f  _file] object (o
b640: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79  r, more commonly
b650: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  , a subclass of 
b660: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
b670: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69  file] object) wi
b680: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  th a pointer to 
b690: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
b6a0: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54  his object..** T
b6b0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
b6c0: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75  es the methods u
b6d0: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  sed to perform v
b6e0: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e  arious operation
b6f0: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65  s.** against the
b700: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65   open file repre
b710: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73  sented by the [s
b720: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
b730: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ect..**.** If th
b740: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
b750: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74  Open] method set
b760: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  s the sqlite3_fi
b770: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
b780: 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e  ent .** to a non
b790: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
b7a0: 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
b7b0: 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73  io_methods.xClos
b7c0: 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20  e method.** may 
b7d0: 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20  be invoked even 
b7e0: 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  if the [sqlite3_
b7f0: 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72  vfs.xOpen] repor
b800: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c  ted that it fail
b810: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79  ed.  The.** only
b820: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20   way to prevent 
b830: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65  a call to xClose
b840: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
b850: 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  led [sqlite3_vfs
b860: 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f  .xOpen].** is fo
b870: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  r the [sqlite3_v
b880: 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74  fs.xOpen] to set
b890: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
b8a0: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
b8b0: 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  nt.** to NULL..*
b8c0: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
b8d0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63  rgument to xSync
b8e0: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b   may be one of [
b8f0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
b900: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  AL] or.** [SQLIT
b910: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54  E_SYNC_FULL].  T
b920: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20  he first choice 
b930: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73  is the normal fs
b940: 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65  ync()..** The se
b950: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61  cond choice is a
b960: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
b970: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b  fullsync.  The [
b980: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
b990: 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61  ONLY].** flag ma
b9a0: 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20  y be ORed in to 
b9b0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e  indicate that on
b9c0: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74  ly the data of t
b9d0: 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e  he file.** and n
b9e0: 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65  ot its inode nee
b9f0: 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e  ds to be synced.
ba00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67  .**.** The integ
ba10: 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f  er values to xLo
ba20: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
ba30: 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a  () are one of.**
ba40: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
ba50: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
ba60: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
ba70: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
ba80: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
ba90: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a  LOCK_RESERVED],.
baa0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
bab0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
bac0: 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
bad0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
bae0: 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78  ]..** </ul>.** x
baf0: 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73  Lock() increases
bb00: 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f   the lock. xUnlo
bb10: 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74  ck() decreases t
bb20: 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20  he lock..** The 
bb30: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
bb40: 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63  ck() method chec
bb50: 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64  ks whether any d
bb60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
bb70: 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e  on,.** either in
bb80: 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72   this process or
bb90: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70   in some other p
bba0: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69  rocess, is holdi
bbb0: 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a  ng a RESERVED,.*
bbc0: 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58  * PENDING, or EX
bbd0: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20  CLUSIVE lock on 
bbe0: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65  the file.  It re
bbf0: 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66  turns true.** if
bc00: 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69   such a lock exi
bc10: 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74  sts and false ot
bc20: 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54  herwise..**.** T
bc30: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
bc40: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
bc50: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
bc60: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
bc70: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
bc80: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
bc90: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
bca0: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
bcb0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
bcc0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
bcd0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
bce0: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
bcf0: 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69  ument is an.** i
bd00: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
bd10: 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
bd20: 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  nt is a generic 
bd30: 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64  pointer intended
bd40: 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20   to.** point to 
bd50: 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  a structure that
bd60: 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67   may contain arg
bd70: 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20  uments or space 
bd80: 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77  in which to.** w
bd90: 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75  rite return valu
bda0: 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75  es.  Potential u
bdb0: 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e  ses for xFileCon
bdc0: 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a  trol() might be.
bdd0: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20  ** functions to 
bde0: 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20  enable blocking 
bdf0: 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f  locks with timeo
be00: 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74  uts, to change t
be10: 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74  he.** locking st
be20: 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d  rategy (for exam
be30: 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66  ple to use dot-f
be40: 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69  ile locks), to i
be50: 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20  nquire.** about 
be60: 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20  the status of a 
be70: 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61  lock, or to brea
be80: 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20  k stale locks.  
be90: 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f  The SQLite.** co
bea0: 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20  re reserves all 
beb0: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61  opcodes less tha
bec0: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77  n 100 for its ow
bed0: 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c  n use..** A [SQL
bee0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
bef0: 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  ATE | list of op
bf00: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
bf10: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
bf20: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
bf30: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
bf40: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
bf50: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
bf60: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a  ld use opcodes.*
bf70: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
bf80: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
bf90: 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c  licts.  VFS impl
bfa0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
bfb0: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
bfc0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66  LITE_NOTFOUND] f
bfd0: 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  or file control 
bfe0: 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65  opcodes that the
bff0: 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f  y do not.** reco
c000: 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  gnize..**.** The
c010: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
c020: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
c030: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
c040: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
c050: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
c060: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
c070: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
c080: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
c090: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
c0a0: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
c0b0: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
c0c0: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
c0d0: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
c0e0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
c0f0: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
c100: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
c110: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
c120: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
c130: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
c140: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
c150: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
c160: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
c170: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
c180: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
c190: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
c1a0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
c1b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
c1c0: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
c1d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
c1e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
c1f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
c200: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
c210: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
c220: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
c230: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
c240: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
c250: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
c260: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
c270: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
c280: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
c290: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
c2a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
c2b0: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  NTIAL].** </ul>.
c2c0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
c2d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
c2e0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
c2f0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
c300: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
c310: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
c320: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
c330: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
c340: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
c350: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
c360: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
c370: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
c380: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
c390: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
c3a0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
c3b0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
c3c0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
c3d0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
c3e0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
c3f0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
c400: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
c410: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
c420: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
c430: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
c440: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
c450: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
c460: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
c470: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
c480: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
c490: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
c4a0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
c4b0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
c4c0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
c4d0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
c4e0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
c4f0: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a  to xWrite()..**.
c500: 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65  ** If xRead() re
c510: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45  turns SQLITE_IOE
c520: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74  RR_SHORT_READ it
c530: 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a   must also fill.
c540: 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64  ** in the unread
c550: 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65   portions of the
c560: 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72   buffer with zer
c570: 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a  os.  A VFS that.
c580: 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f  ** fails to zero
c590: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
c5a0: 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20  s might seem to 
c5b0: 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a  work.  However,.
c5c0: 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65  ** failure to ze
c5d0: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
c5e0: 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  ads will eventua
c5f0: 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64  lly lead to.** d
c600: 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
c610: 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
c620: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
c630: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
c640: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
c650: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
c660: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
c670: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
c680: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
c690: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
c6a0: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
c6b0: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
c6c0: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
c6d0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
c6e0: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71  int (*xWrite)(sq
c6f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e  lite3_file*, con
c700: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  st void*, int iA
c710: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
c720: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
c730: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c  (*xTruncate)(sql
c740: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
c750: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b  te3_int64 size);
c760: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
c770: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
c780: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
c790: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71   (*xFileSize)(sq
c7a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
c7b0: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a  ite3_int64 *pSiz
c7c0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63  e);.  int (*xLoc
c7d0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
c7e0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
c7f0: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33  xUnlock)(sqlite3
c800: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
c810: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65  int (*xCheckRese
c820: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65  rvedLock)(sqlite
c830: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52  3_file*, int *pR
c840: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
c850: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71  xFileControl)(sq
c860: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
c870: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29   op, void *pArg)
c880: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f  ;.  int (*xSecto
c890: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  rSize)(sqlite3_f
c8a0: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
c8b0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
c8c0: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66  stics)(sqlite3_f
c8d0: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  ile*);.  /* Meth
c8e0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
c8f0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
c900: 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68  1 */.  int (*xSh
c910: 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  mMap)(sqlite3_fi
c920: 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e  le*, int iPg, in
c930: 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69  t pgsz, int, voi
c940: 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20  d volatile**);. 
c950: 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29   int (*xShmLock)
c960: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
c970: 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20  int offset, int 
c980: 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  n, int flags);. 
c990: 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72   void (*xShmBarr
c9a0: 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ier)(sqlite3_fil
c9b0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  e*);.  int (*xSh
c9c0: 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f  mUnmap)(sqlite3_
c9d0: 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74  file*, int delet
c9e0: 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74  eFlag);.  /* Met
c9f0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
ca00: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
ca10: 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74   2 */.  /* Addit
ca20: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61  ional methods ma
ca30: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
ca40: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f  ture releases */
ca50: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
ca60: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69  REF: Standard Fi
ca70: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64  le Control Opcod
ca80: 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  es.**.** These i
ca90: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
caa0: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72   are opcodes for
cab0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
cac0: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  l method.** of t
cad0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
cae0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61  ethods] object a
caf0: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  nd for the [sqli
cb00: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
cb10: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
cb20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
cb30: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
cb40: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
cb50: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
cb60: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
cb70: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
cb80: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
cb90: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
cba0: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
cbb0: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
cbc0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
cbd0: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
cbe0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
cbf0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
cc00: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
cc10: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
cc20: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
cc30: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
cc40: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
cc50: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
cc60: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
cc70: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
cc80: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
cc90: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f  ng testing and o
cca0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
ccb0: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
ccc0: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73  QLITE_TEST.** is
ccd0: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c   defined..** <ul
cce0: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  >.** <li>[[SQLIT
ccf0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
cd00: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
cd10: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
cd20: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
cd30: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
cd40: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
cd50: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
cd60: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
cd70: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
cd80: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
cd90: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
cda0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
cdb0: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
cdc0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
cdd0: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
cde0: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
cdf0: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
ce00: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
ce10: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
ce20: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
ce30: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
ce40: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
ce50: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
ce60: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
ce70: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
ce80: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
ce90: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
cea0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
ceb0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
cec0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
ced0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
cee0: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
cef0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
cf00: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
cf10: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
cf20: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
cf30: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
cf40: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
cf50: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
cf60: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
cf70: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
cf80: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
cf90: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
cfa0: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
cfb0: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
cfc0: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
cfd0: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
cfe0: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
cff0: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
d000: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
d010: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
d020: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
d030: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
d040: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
d050: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
d060: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
d070: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
d080: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
d090: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
d0a0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
d0b0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
d0c0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
d0d0: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
d0e0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
d0f0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
d100: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
d110: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
d120: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
d130: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
d140: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
d150: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
d160: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63  e_control()] doc
d170: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  umentation for.*
d180: 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
d190: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
d1a0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
d1b0: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
d1c0: 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49  ].** ^(The [SQLI
d1d0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
d1e0: 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73  ITTED] opcode is
d1f0: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
d200: 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69  nally by.** SQLi
d210: 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61  te and sent to a
d220: 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63  ll VFSes in plac
d230: 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74  e of a call to t
d240: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a  he xSync method.
d250: 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  ** when the data
d260: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
d270: 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  has [PRAGMA sync
d280: 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20  hronous] set to 
d290: 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73  OFF.)^.** Some s
d2a0: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
d2b0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
d2c0: 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70  l in order to op
d2d0: 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a  erate correctly.
d2e0: 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20  ** when [PRAGMA 
d2f0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52  synchronous | PR
d300: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
d310: 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75  =OFF] is set, bu
d320: 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73  t most .** VFSes
d330: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
d340: 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f  s signal and sho
d350: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
d360: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
d370: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
d380: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
d390: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
d3a0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
d3b0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73  his.** opcode as
d3c0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
d3d0: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
d3e0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
d3f0: 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20  alized VFSes.** 
d400: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
d410: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
d420: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
d430: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a  IN32_AV_RETRY]].
d440: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
d450: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
d460: 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETRY] opcode is 
d470: 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
d480: 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72  e automatic.** r
d490: 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20  etry counts and 
d4a0: 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65  intervals for ce
d4b0: 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f  rtain disk I/O o
d4c0: 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68  perations for th
d4d0: 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46  e.** windows [VF
d4e0: 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  S] in order to p
d4f0: 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73  rovide robustnes
d500: 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63  s in the presenc
d510: 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72  e of.** anti-vir
d520: 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79  us programs.  By
d530: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69   default, the wi
d540: 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72  ndows VFS will r
d550: 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a  etry file read,.
d560: 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61  ** file write, a
d570: 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f  nd file delete o
d580: 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20  perations up to 
d590: 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61  10 times, with a
d5a0: 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20   delay.** of 25 
d5b0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66  milliseconds bef
d5c0: 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65  ore the first re
d5d0: 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65  try and with the
d5e0: 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e   delay increasin
d5f0: 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74  g.** by an addit
d600: 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65  ional 25 millise
d610: 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20  conds with each 
d620: 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79  subsequent retry
d630: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
d640: 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74  e allows these t
d650: 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65  wo values (10 re
d660: 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c  tries and 25 mil
d670: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c  liseconds of del
d680: 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a  ay).** to be adj
d690: 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75  usted.  The valu
d6a0: 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66  es are changed f
d6b0: 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20  or all database 
d6c0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77  connections.** w
d6d0: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70  ithin the same p
d6e0: 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67  rocess.  The arg
d6f0: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
d700: 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f  er to an array o
d710: 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72  f two.** integer
d720: 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73  s where the firs
d730: 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20  t integer i the 
d740: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20  new retry count 
d750: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  and the second.*
d760: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65  * integer is the
d770: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68   delay.  If eith
d780: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65  er integer is ne
d790: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
d7a0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e   setting.** is n
d7b0: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69  ot changed but i
d7c0: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72  nstead the prior
d7d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73   value of that s
d7e0: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65  etting is writte
d7f0: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72  n.** into the ar
d800: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77  ray entry, allow
d810: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20  ing the current 
d820: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74  retry settings t
d830: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67  o be.** interrog
d840: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61  ated.  The zDbNa
d850: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
d860: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  ignored..**.** <
d870: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
d880: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a  L_PERSIST_WAL]].
d890: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
d8a0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
d8b0: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  L] opcode is use
d8c0: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
d8d0: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
d8e0: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65  ent [WAL | Write
d8f0: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74   Ahead Log] sett
d900: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ing.  By default
d910: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a  , the auxiliary.
d920: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c  ** write ahead l
d930: 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  og and shared me
d940: 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20  mory files used 
d950: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  for transaction 
d960: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61  control.** are a
d970: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
d980: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61  eted when the la
d990: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  test connection 
d9a0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
d9b0: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74  ** closes.  Sett
d9c0: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57  ing persistent W
d9d0: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74  AL mode causes t
d9e0: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65  hose files to pe
d9f0: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63  rsist after.** c
da00: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e  lose.  Persistin
da10: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75  g the files is u
da20: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72  seful when other
da30: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20   processes that 
da40: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77  do not.** have w
da50: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20  rite permission 
da60: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  on the directory
da70: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
da80: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
da90: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68  nt.** to read th
daa0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
dab0: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20   as the WAL and 
dac0: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
dad0: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a  les must exist.*
dae0: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74  * in order for t
daf0: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62  he database to b
db00: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  e readable.  The
db10: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
db20: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
db30: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
db40: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
db50: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
db60: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
db70: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
db80: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
db90: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57  ble persistent W
dba0: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  AL mode or 1 to 
dbb0: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  enable persisten
dbc0: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20  t.** WAL mode.  
dbd0: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
dbe0: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
dbf0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
dc00: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
dc10: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65   WAL persistence
dc20: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
dc30: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
dc40: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
dc50: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
dc60: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
dc70: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
dc80: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
dc90: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
dca0: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
dcb0: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d  tent "powersafe-
dcc0: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50  overwrite" or "P
dcd0: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54  SOW" setting.  T
dce0: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a  he PSOW setting.
dcf0: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  ** determines th
dd00: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  e [SQLITE_IOCAP_
dd10: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
dd20: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a  ITE] bit of the.
dd30: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63  ** xDeviceCharac
dd40: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
dd50: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  s. The fourth pa
dd60: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
dd70: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
dd80: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
dd90: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
dda0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
ddb0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
ddc0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
ddd0: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64  o disable zero-d
dde0: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20  amage mode or 1 
ddf0: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64  to enable zero-d
de00: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20  amage.** mode.  
de10: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
de20: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
de30: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
de40: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
de50: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
de60: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
de70: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
de80: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  NTL_OVERWRITE]].
de90: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
dea0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
deb0: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
dec0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
ded0: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
dee0: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
def0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
df00: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
df10: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
df20: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
df30: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
df40: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
df50: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
df60: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
df70: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
df80: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
df90: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
dfa0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
dfb0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
dfc0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
dfd0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
dfe0: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
dff0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
e000: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20  the names of.** 
e010: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74  all [VFSes] in t
e020: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54  he VFS stack.  T
e030: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20  he names are of 
e040: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e  all VFS shims an
e050: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62  d the.** final b
e060: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20  ottom-level VFS 
e070: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  are written into
e080: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
e090: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
e0a0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
e0b0: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73   the result is s
e0c0: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61  tored in the cha
e0d0: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74  r* variable.** t
e0e0: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70  hat the fourth p
e0f0: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
e100: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
e110: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a  l()] points to..
e120: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73  ** The caller is
e130: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
e140: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
e150: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20  ory when done.  
e160: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66  As with.** all f
e170: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69  ile-control acti
e180: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f  ons, there is no
e190: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
e1a0: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c  this will actual
e1b0: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e  ly.** do anythin
e1c0: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75  g.  Callers shou
e1d0: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68  ld initialize th
e1e0: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
e1f0: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   to a NULL.** po
e200: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68  inter in case th
e210: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
e220: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
e230: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63  ed.  This file-c
e240: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74  ontrol.** is int
e250: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f  ended for diagno
e260: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a  stic use only..*
e270: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
e280: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d  E_FCNTL_PRAGMA]]
e290: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20  .** ^Whenever a 
e2a0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
e2b0: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e  nt is parsed, an
e2c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
e2d0: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20  RAGMA] .** file 
e2e0: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20  control is sent 
e2f0: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c  to the open [sql
e300: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
e310: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  t corresponding.
e320: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ** to the databa
e330: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68  se file to which
e340: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74   the pragma stat
e350: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54  ement refers. ^T
e360: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
e370: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  o the [SQLITE_FC
e380: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
e390: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61   control is an a
e3a0: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74  rray of.** point
e3b0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28  ers to strings (
e3c0: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68  char**) in which
e3d0: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d   the second elem
e3e0: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79  ent of the array
e3f0: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
e400: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e  of the pragma an
e410: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d  d the third elem
e420: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ent is the argum
e430: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72  ent to the.** pr
e440: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20  agma or NULL if 
e450: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e  the pragma has n
e460: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  o argument.  ^Th
e470: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e  e handler for an
e480: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
e490: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
e4a0: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f  ontrol can optio
e4b0: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66  nally make the f
e4c0: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  irst element.** 
e4d0: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72  of the char** ar
e4e0: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20  gument point to 
e4f0: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  a string obtaine
e500: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
e510: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72  mprintf()].** or
e520: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
e530: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20  and that string 
e540: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
e550: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72  result of the pr
e560: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65  agma or.** the e
e570: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20  rror message if 
e580: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73  the pragma fails
e590: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51  . ^If the.** [SQ
e5a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
e5b0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
e5c0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
e5d0: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20  NOTFOUND], then 
e5e0: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47  normal .** [PRAG
e5f0: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63  MA] processing c
e600: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74  ontinues.  ^If t
e610: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
e620: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
e630: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
e640: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
e650: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73  en the parser as
e660: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
e670: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65  * VFS has handle
e680: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73  d the PRAGMA its
e690: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73  elf and the pars
e6a0: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e  er generates a n
e6b0: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64  o-op.** prepared
e6c0: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66   statement.  ^If
e6d0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
e6e0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
e6f0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a  control returns.
e700: 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f  ** any result co
e710: 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  de other than [S
e720: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51  QLITE_OK] or [SQ
e730: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
e740: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  that means.** th
e750: 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75  at the VFS encou
e760: 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20  ntered an error 
e770: 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74  while handling t
e780: 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20  he [PRAGMA] and 
e790: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69  the.** compilati
e7a0: 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41  on of the PRAGMA
e7b0: 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65   fails with an e
e7c0: 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c  rror.  ^The [SQL
e7d0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
e7e0: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
e7f0: 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20  l occurs at the 
e800: 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61  beginning of pra
e810: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  gma statement an
e820: 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a  alysis and so.**
e830: 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f   it is able to o
e840: 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e  verride built-in
e850: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
e860: 65 6e 74 73 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ents..** </ul>.*
e870: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e880: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
e890: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
e8a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e8b0: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
e8c0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a  E             2.
e8d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
e8e0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
e8f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
e900: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41  define SQLITE_LA
e910: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
e920: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
e930: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
e940: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
e950: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
e960: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
e970: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20  L_CHUNK_SIZE    
e980: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
e990: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
e9a0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
e9b0: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
e9c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
e9d0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
e9e0: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e          8.#defin
e9f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
ea00: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20  IN32_AV_RETRY   
ea10: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
ea20: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45   SQLITE_FCNTL_PE
ea30: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20  RSIST_WAL       
ea40: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
ea50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
ea60: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  RWRITE          
ea70: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53      11.#define S
ea80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
ea90: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20  AME             
eaa0: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
eab0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
eac0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
ead0: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    13.#define SQL
eae0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
eaf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
eb00: 20 31 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   14../*.** CAPI3
eb10: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
eb20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  e.**.** The mute
eb30: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
eb40: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
eb50: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
eb60: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
eb70: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
eb80: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
eb90: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
eba0: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
ebb0: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
ebc0: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
ebd0: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
ebe0: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
ebf0: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
ec00: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
ec10: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
ec20: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
ec30: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
ec40: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
ec50: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
ec60: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
ec70: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
ec80: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
ec90: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
eca0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
ecb0: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
ecc0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
ecd0: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
ece0: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
ecf0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
ed00: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
ed10: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
ed20: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
ed30: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
ed40: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
ed50: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
ed60: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
ed70: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
ed80: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
ed90: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
eda0: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
edb0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
edc0: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  The value of the
edd0: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
ede0: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
edf0: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
ee00: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65   in.** future ve
ee10: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
ee20: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
ee30: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
ee40: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
ee50: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
ee60: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
ee70: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f  s increased.  No
ee80: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
ee90: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
eea0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
eeb0: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
eec0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
eed0: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  tween.** SQLite 
eee0: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e  version 3.5.9 an
eef0: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20  d 3.6.0 and yet 
ef00: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
ef10: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f  ld was not.** mo
ef20: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
ef30: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
ef40: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
ef50: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
ef60: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
ef70: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
ef80: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
ef90: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
efa0: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
efb0: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
efc0: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
efd0: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
efe0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
eff0: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
f000: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
f010: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
f020: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
f030: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
f040: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
f050: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
f060: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
f070: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
f080: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
f090: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
f0a0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
f0b0: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
f0c0: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
f0d0: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
f0e0: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
f0f0: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
f100: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
f110: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
f120: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
f130: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
f140: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
f150: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
f160: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
f170: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
f180: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
f190: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
f1a0: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
f1b0: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
f1c0: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
f1d0: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
f1e0: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
f1f0: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
f200: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
f210: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
f220: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
f230: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
f240: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
f250: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
f260: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
f270: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
f280: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
f290: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
f2a0: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
f2b0: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
f2c0: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
f2d0: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73  dules..**.** [[s
f2e0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
f2f0: 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  ]].** ^SQLite gu
f300: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
f310: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
f320: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
f330: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
f340: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
f350: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
f360: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
f370: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
f380: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
f390: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
f3a0: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
f3b0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
f3c0: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
f3d0: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
f3e0: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
f3f0: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
f400: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
f410: 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72  ** 11 alphanumer
f420: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
f430: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
f440: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
f450: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
f460: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
f470: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
f480: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
f490: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
f4a0: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
f4b0: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
f4c0: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
f4d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
f4e0: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
f4f0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
f500: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
f510: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
f520: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
f530: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
f540: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
f550: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
f560: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
f570: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
f580: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
f590: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
f5a0: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
f5b0: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
f5c0: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
f5d0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
f5e0: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
f5f0: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
f600: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
f610: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
f620: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
f630: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
f640: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
f650: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
f660: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
f670: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
f680: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
f690: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
f6a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
f6b0: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
f6c0: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
f6d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
f6e0: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
f6f0: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
f700: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
f710: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
f720: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
f730: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
f740: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
f750: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
f760: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
f770: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
f780: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
f790: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
f7a0: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
f7b0: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
f7c0: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
f7d0: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
f7e0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
f7f0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
f800: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
f810: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
f820: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
f830: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
f840: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
f850: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
f860: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
f870: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
f880: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
f890: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
f8a0: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
f8b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
f8c0: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
f8d0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
f8e0: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
f8f0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
f900: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
f910: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
f920: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
f930: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
f940: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
f950: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
f960: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
f970: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f980: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
f990: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
f9a0: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
f9b0: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
f9c0: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
f9d0: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
f9e0: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
f9f0: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
fa00: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
fa10: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
fa20: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
fa30: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
fa40: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
fa50: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
fa60: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
fa70: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
fa80: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
fa90: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
faa0: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
fab0: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
fac0: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
fad0: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
fae0: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
faf0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
fb00: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
fb10: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
fb20: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
fb30: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
fb40: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
fb50: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
fb60: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
fb70: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
fb80: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
fb90: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
fba0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
fbb0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
fbc0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
fbd0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
fbe0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
fbf0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
fc00: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
fc10: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
fc20: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
fc30: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
fc40: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
fc50: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
fc60: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
fc70: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
fc80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
fc90: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
fca0: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
fcb0: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
fcc0: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
fcd0: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
fce0: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
fcf0: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
fd00: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
fd10: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
fd20: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
fd30: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
fd40: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
fd50: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
fd60: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
fd70: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
fd80: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
fd90: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
fda0: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
fdb0: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
fdc0: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
fdd0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
fde0: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
fdf0: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
fe00: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
fe10: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
fe20: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
fe30: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
fe40: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
fe50: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
fe60: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
fe70: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
fe80: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
fe90: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
fea0: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
feb0: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
fec0: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
fed0: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
fee0: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
fef0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
ff00: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
ff10: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
ff20: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
ff30: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
ff40: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
ff50: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
ff60: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
ff70: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
ff80: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
ff90: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
ffa0: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
ffb0: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
ffc0: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
ffd0: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
ffe0: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
fff0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
10000 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
10010 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
10020 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
10030 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
10040 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
10050 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
10060 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
10070 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
10080 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
10090 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
100a0 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
100b0 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
100c0 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
100d0 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
100e0 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
100f0 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
10100 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b  en call..**.** [
10110 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63  [sqlite3_vfs.xAc
10120 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66  cess]].** ^The f
10130 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
10140 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
10150 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
10160 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74  _EXISTS].** to t
10170 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
10180 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tence of a file,
10190 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
101a0 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f  SS_READWRITE] to
101b0 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72  .** test whether
101c0 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
101d0 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
101e0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
101f0 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
10200 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
10210 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
10220 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20  readable.   The 
10230 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
10240 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
10250 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  * ^SQLite will a
10260 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
10270 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
10280 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
10290 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
102a0 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
102b0 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69  e.  The exact si
102c0 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
102d0 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
102e0 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
102f0 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
10300 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68    methods. If th
10310 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
10320 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
10330 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
10340 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
10350 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
10360 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
10370 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
10380 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
10390 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
103a0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
103b0 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
103c0 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
103d0 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
103e0 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
103f0 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
10400 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
10410 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
10420 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  , xCurrentTime()
10430 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
10440 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74  meInt64().** int
10450 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20  erfaces are not 
10460 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
10470 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
10480 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
10490 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
104a0 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
104b0 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
104c0 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
104d0 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
104e0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
104f0 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
10500 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
10510 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
10520 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
10530 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
10540 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
10550 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
10560 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
10570 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
10580 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
10590 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
105a0 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
105b0 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
105c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
105d0 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
105e0 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54    ^The xCurrentT
105f0 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ime().** method 
10600 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e  returns a Julian
10610 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20   Day Number for 
10620 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65  the current date
10630 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20   and time as.** 
10640 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
10650 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20   value..** ^The 
10660 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
10670 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  4() method retur
10680 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65  ns, as an intege
10690 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a  r, the Julian.**
106a0 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74   Day Number mult
106b0 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30  iplied by 864000
106c0 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f  00 (the number o
106d0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69  f milliseconds i
106e0 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20  n .** a 24-hour 
106f0 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69  day).  .** ^SQLi
10700 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
10710 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
10720 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65  4() method to ge
10730 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  t the current.**
10740 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69   date and time i
10750 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73  f that method is
10760 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69   available (if i
10770 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20  Version is 2 or 
10780 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20  .** greater and 
10790 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
107a0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
107b0 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20  ) and will fall 
107c0 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72  back.** to xCurr
107d0 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75  entTime() if xCu
107e0 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
107f0 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
10800 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74  .**.** ^The xSet
10810 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47  SystemCall(), xG
10820 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
10830 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43  and xNestSystemC
10840 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73  all() interfaces
10850 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64  .** are not used
10860 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63   by the SQLite c
10870 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69  ore.  These opti
10880 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  onal interfaces 
10890 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  are provided.** 
108a0 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f  by some VFSes to
108b0 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74   facilitate test
108c0 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63  ing of the VFS c
108d0 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69  ode. By overridi
108e0 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61  ng .** system ca
108f0 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f  lls with functio
10900 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e  ns under its con
10910 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f  trol, a test pro
10920 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75  gram can.** simu
10930 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20  late faults and 
10940 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73  error conditions
10950 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65   that would othe
10960 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75  rwise be difficu
10970 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69  lt.** or impossi
10980 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20  ble to induce.  
10990 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65  The set of syste
109a0 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e  m calls that can
109b0 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a   be overridden.*
109c0 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  * varies from on
109d0 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72  e VFS to another
109e0 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76  , and from one v
109f0 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61  ersion of the sa
10a00 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a  me VFS to the.**
10a10 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
10a20 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68  ions that use th
10a30 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
10a40 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20  ust be prepared 
10a50 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c  for any.** or al
10a60 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72  l of these inter
10a70 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c  faces to be NULL
10a80 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65   or for their be
10a90 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65  havior to change
10aa0 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c  .** from one rel
10ab0 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74  ease to the next
10ac0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
10ad0 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74  must not attempt
10ae0 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e   to access.** an
10af0 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f  y of these metho
10b00 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69  ds if the iVersi
10b10 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73  on of the VFS is
10b20 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f   less than 3..*/
10b30 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
10b40 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
10b50 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66  te3_vfs;.typedef
10b60 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
10b70 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69  syscall_ptr)(voi
10b80 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  d);.struct sqlit
10b90 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
10ba0 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
10bb0 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
10bc0 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
10bd0 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f  (currently 3) */
10be0 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
10bf0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
10c00 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
10c10 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
10c20 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
10c30 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
10c40 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
10c50 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
10c60 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
10c70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
10c80 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
10c90 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
10ca0 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
10cb0 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
10cc0 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
10cd0 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
10ce0 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
10cf0 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
10d00 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
10d10 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
10d20 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
10d30 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
10d40 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
10d50 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
10d60 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
10d70 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
10d80 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
10d90 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
10da0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
10db0 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
10dc0 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
10dd0 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
10de0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
10df0 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
10e00 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
10e10 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
10e20 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
10e30 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
10e40 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
10e50 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
10e60 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
10e70 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
10e80 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
10e90 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
10ea0 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
10eb0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
10ec0 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
10ed0 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a  rMsg);.  void (*
10ee0 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
10ef0 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
10f00 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
10f10 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69  l))(void);.  voi
10f20 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71  d (*xDlClose)(sq
10f30 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64  lite3_vfs*, void
10f40 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e  *);.  int (*xRan
10f50 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33  domness)(sqlite3
10f60 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
10f70 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
10f80 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73   int (*xSleep)(s
10f90 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
10fa0 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a   microseconds);.
10fb0 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
10fc0 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Time)(sqlite3_vf
10fd0 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20  s*, double*);.  
10fe0 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72  int (*xGetLastEr
10ff0 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
11000 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b  *, int, char *);
11010 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
11020 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
11030 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66   in version 1 of
11040 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
11050 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69  object.  ** defi
11060 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74  nition.  Those t
11070 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61  hat follow are a
11080 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20  dded in version 
11090 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a  2 or later.  */.
110a0 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
110b0 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74  TimeInt64)(sqlit
110c0 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33  e3_vfs*, sqlite3
110d0 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20  _int64*);.  /*. 
110e0 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
110f0 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
11100 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66  sions 1 and 2 of
11110 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
11120 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f  object..  ** Tho
11130 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72  se below are for
11140 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67   version 3 and g
11150 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69  reater..  */.  i
11160 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43  nt (*xSetSystemC
11170 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
11180 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
11190 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79  Name, sqlite3_sy
111a0 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71  scall_ptr);.  sq
111b0 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
111c0 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61  r (*xGetSystemCa
111d0 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
111e0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
111f0 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68  ame);.  const ch
11200 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65  ar *(*xNextSyste
11210 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
11220 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
11230 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20  *zName);.  /*.  
11240 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
11250 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
11260 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33  ions 1 through 3
11270 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
11280 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
11290 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
112a0 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69  e appended in fi
112b0 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  gure versions.  
112c0 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
112d0 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
112e0 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
112f0 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20  this happens. . 
11300 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
11310 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
11320 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46  r the xAccess VF
11330 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
11340 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
11350 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73  stants can be us
11360 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
11370 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
11380 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
11390 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  od of an [sqlite
113a0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
113b0 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
113c0 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70  * what kind of p
113d0 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78  ermissions the x
113e0 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73  Access method is
113f0 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a   looking for..**
11400 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
11410 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
11420 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
11430 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
11440 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
11450 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68   exists..** With
11460 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
11470 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41  EADWRITE, the xA
11480 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
11490 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
114a0 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f  he named directo
114b0 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61  ry is both reada
114c0 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
114d0 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f  .** (in other wo
114e0 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61  rds, if files ca
114f0 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f  n be added, remo
11500 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64  ved, and renamed
11510 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64   within.** the d
11520 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68  irectory)..** Th
11530 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
11540 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61  READWRITE consta
11550 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  nt is currently 
11560 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65  used only by the
11570 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  .** [temp_store_
11580 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
11590 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63  ], though this c
115a0 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61  ould change in a
115b0 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
115c0 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
115d0 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
115e0 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
115f0 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
11600 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
11610 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
11620 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ble.  The SQLITE
11630 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e  _ACCESS_READ con
11640 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72  stant is.** curr
11650 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68  ently unused, th
11660 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65  ough it might be
11670 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72   used in a futur
11680 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
11690 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
116a0 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
116b0 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
116c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
116d0 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20  SS_READWRITE 1  
116e0 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47   /* Used by PRAG
116f0 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  MA temp_store_di
11700 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69  rectory */.#defi
11710 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
11720 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f  _READ      2   /
11730 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  * Unused */../*.
11740 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
11750 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c  gs for the xShmL
11760 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ock VFS method.*
11770 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
11780 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  er constants def
11790 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20  ine the various 
117a0 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f  locking operatio
117b0 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79  ns.** allowed by
117c0 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   the xShmLock me
117d0 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  thod of [sqlite3
117e0 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54  _io_methods].  T
117f0 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
11800 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67  are the only leg
11810 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  al combinations 
11820 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a  of flags to the.
11830 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  ** xShmLock meth
11840 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
11850 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
11860 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
11870 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
11880 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
11890 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
118a0 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
118b0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
118c0 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
118d0 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
118e0 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
118f0 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
11900 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
11910 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  </ul>.**.** When
11920 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20   unlocking, the 
11930 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45  same SHARED or E
11940 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75  XCLUSIVE flag mu
11950 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61  st be supplied a
11960 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e  s.** was given n
11970 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
11980 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a  ing lock.  .**.*
11990 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
119a0 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69  ethod can transi
119b0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c  tion between unl
119c0 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44  ocked and SHARED
119d0 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75   or.** between u
119e0 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c  nlocked and EXCL
119f0 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f  USIVE.  It canno
11a00 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  t transition bet
11a10 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61  ween SHARED.** a
11a20 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f  nd EXCLUSIVE..*/
11a30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11a40 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  SHM_UNLOCK      
11a50 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
11a60 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20  E_SHM_LOCK      
11a70 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
11a80 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20  ITE_SHM_SHARED  
11a90 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
11aa0 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
11ab0 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20  IVE    8../*.** 
11ac0 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75  CAPI3REF: Maximu
11ad0 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78  m xShmLock index
11ae0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
11af0 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73  ock method on [s
11b00 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
11b10 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65  s] may use value
11b20 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61  s.** between 0 a
11b30 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f  nd this upper bo
11b40 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73  und as its "offs
11b50 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  et" argument..**
11b60 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
11b70 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65   will never atte
11b80 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f  mpt to acquire o
11b90 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c  r release a.** l
11ba0 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74  ock outside of t
11bb0 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65  his range.*/.#de
11bc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
11bd0 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a  NLOCK        8..
11be0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11bf0 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
11c00 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
11c10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
11c20 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
11c30 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
11c40 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
11c50 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
11c60 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11c70 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
11c80 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
11c90 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
11ca0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
11cb0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11cc0 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
11cd0 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
11ce0 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
11cf0 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
11d00 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
11d10 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
11d20 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
11d30 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
11d40 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
11d50 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
11d60 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
11d70 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
11d80 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
11d90 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
11da0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11db0 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
11dc0 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
11dd0 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
11de0 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
11df0 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
11e00 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
11e10 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
11e20 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
11e30 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
11e40 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
11e50 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
11e60 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
11e70 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
11e80 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
11e90 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
11ea0 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
11eb0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11ec0 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
11ed0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
11ee0 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
11ef0 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
11f00 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
11f10 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
11f20 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
11f30 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
11f40 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
11f50 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
11f60 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
11f70 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
11f80 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
11f90 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
11fa0 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
11fb0 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
11fc0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
11fd0 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
11fe0 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
11ff0 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
12000 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
12010 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
12020 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
12030 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12040 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
12050 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
12060 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
12070 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
12080 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
12090 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
120a0 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
120b0 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
120c0 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
120d0 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
120e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
120f0 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
12100 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
12110 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
12120 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
12130 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
12140 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
12150 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
12160 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
12170 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
12180 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
12190 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
121a0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
121b0 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
121c0 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
121d0 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
121e0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
121f0 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
12200 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
12210 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
12220 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
12230 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
12240 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
12250 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
12260 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
12270 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
12280 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
12290 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
122a0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
122b0 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
122c0 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
122d0 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
122e0 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
122f0 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
12300 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
12310 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
12320 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12330 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
12340 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
12350 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
12360 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
12370 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
12380 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
12390 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
123a0 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
123b0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
123c0 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
123d0 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
123e0 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
123f0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
12400 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
12410 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
12420 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
12430 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
12440 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
12450 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
12460 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
12470 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
12480 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
12490 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
124a0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
124b0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
124c0 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
124d0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
124e0 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
124f0 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
12500 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
12510 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
12520 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
12530 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
12540 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
12550 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
12560 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
12570 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
12580 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
12590 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
125a0 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
125b0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
125c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
125d0 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
125e0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
125f0 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
12600 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
12610 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
12620 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
12630 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
12640 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
12650 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
12660 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
12670 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
12680 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
12690 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
126a0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
126b0 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
126c0 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
126d0 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
126e0 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
126f0 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
12700 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12710 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
12720 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
12730 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
12740 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
12750 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
12760 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
12770 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
12780 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
12790 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
127a0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
127b0 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
127c0 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
127d0 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
127e0 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
127f0 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
12800 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
12810 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
12820 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
12830 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
12840 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
12850 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
12860 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
12870 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
12880 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
12890 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
128a0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
128b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
128c0 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
128d0 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
128e0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
128f0 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
12900 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
12910 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
12920 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
12930 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
12940 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
12950 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
12960 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
12970 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
12980 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
12990 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
129a0 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
129b0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
129c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
129d0 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
129e0 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
129f0 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
12a00 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
12a10 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
12a20 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
12a30 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
12a40 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
12a50 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
12a60 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
12a70 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
12a80 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
12a90 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
12aa0 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
12ab0 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
12ac0 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
12ad0 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
12ae0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
12af0 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
12b00 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
12b10 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
12b20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
12b30 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
12b40 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
12b50 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
12b60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
12b70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
12b80 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
12b90 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
12ba0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
12bb0 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
12bc0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
12bd0 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
12be0 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
12bf0 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
12c00 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  re..*/.SQLITE_AP
12c10 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e  I int sqlite3_in
12c20 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a  itialize(void);.
12c30 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
12c40 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12c50 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
12c60 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  I int sqlite3_os
12c70 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c  _init(void);.SQL
12c80 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
12c90 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
12ca0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12cb0 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
12cc0 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
12cd0 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
12ce0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
12cf0 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
12d00 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
12d10 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
12d20 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
12d30 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
12d40 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
12d50 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
12d60 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
12d70 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
12d80 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
12d90 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
12da0 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
12db0 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
12dc0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
12dd0 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
12de0 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
12df0 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
12e00 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
12e10 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
12e20 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
12e30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
12e40 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
12e50 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
12e60 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
12e70 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
12e80 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
12e90 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
12ea0 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
12eb0 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
12ec0 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
12ed0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
12ee0 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
12ef0 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
12f00 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
12f10 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
12f20 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
12f30 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
12f40 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
12f50 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
12f60 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
12f70 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
12f80 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
12f90 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
12fa0 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
12fb0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12fc0 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
12fd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
12fe0 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
12ff0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
13000 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
13010 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
13020 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
13030 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
13040 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
13050 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
13060 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
13070 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
13080 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
13090 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
130a0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
130b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
130c0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
130d0 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
130e0 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
130f0 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
13100 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
13110 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
13120 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
13130 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
13140 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
13150 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
13160 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
13170 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
13180 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
13190 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
131a0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
131b0 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
131c0 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
131d0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
131e0 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
131f0 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
13200 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
13210 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
13220 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
13230 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
13240 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
13250 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
13260 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
13270 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
13280 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
13290 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
132a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
132b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
132c0 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
132d0 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
132e0 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
132f0 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
13300 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
13310 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
13320 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
13330 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
13340 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
13350 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
13360 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
13370 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
13380 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13390 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
133a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
133b0 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
133c0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
133d0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
133e0 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
133f0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
13400 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
13410 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
13420 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
13430 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
13440 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
13450 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
13460 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13470 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
13480 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
13490 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
134a0 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
134b0 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
134c0 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
134d0 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
134e0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
134f0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
13500 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
13510 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
13520 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
13530 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ssful..*/.SQLITE
13540 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
13550 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
13560 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
13570 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13580 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
13590 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
135a0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
135b0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
135c0 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
135d0 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
135e0 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
135f0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
13600 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
13610 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
13620 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
13630 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
13640 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
13650 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
13660 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
13670 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
13680 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
13690 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
136a0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
136b0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
136c0 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
136d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
136e0 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
136f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
13700 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
13710 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
13720 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
13730 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
13740 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
13750 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
13760 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
13770 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
13780 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
13790 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
137a0 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
137b0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
137c0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
137d0 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
137e0 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
137f0 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
13800 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
13810 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
13820 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
13830 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
13840 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
13850 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
13860 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
13870 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
13880 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
13890 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
138a0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
138b0 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
138c0 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
138d0 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
138e0 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
138f0 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
13900 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
13910 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
13920 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
13930 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
13940 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
13950 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
13960 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
13970 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
13980 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
13990 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
139a0 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
139b0 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
139c0 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
139d0 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
139e0 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
139f0 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
13a00 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
13a10 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c   xMalloc, xReall
13a20 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65  oc, and xFree me
13a30 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
13a40 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
13a50 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
13a60 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
13a70 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
13a80 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
13a90 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ..** ^SQLite gua
13aa0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
13ab0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
13ac0 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
13ad0 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
13ae0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
13af0 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
13b00 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53  oundup..**.** xS
13b10 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
13b20 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
13b30 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
13b40 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
13b50 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
13b60 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
13b70 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
13b80 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
13b90 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
13ba0 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
13bb0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
13bc0 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
13bd0 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
13be0 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
13bf0 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
13c00 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
13c10 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
13c20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
13c30 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
13c40 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
13c50 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
13c60 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
13c70 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
13c80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
13c90 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
13ca0 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
13cb0 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
13cc0 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
13cd0 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
13ce0 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
13cf0 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
13d00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13d10 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
13d20 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
13d30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
13d40 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
13d50 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
13d60 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
13d70 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
13d80 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
13d90 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
13da0 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
13db0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
13dc0 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
13dd0 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
13de0 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
13df0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28  ry allocator.  (
13e00 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
13e10 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
13e20 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
13e30 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
13e40 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
13e50 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
13e60 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
13e70 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
13e80 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
13e90 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
13ea0 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
13eb0 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
13ec0 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
13ed0 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
13ee0 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
13ef0 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
13f00 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
13f10 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
13f20 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
13f30 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
13f40 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
13f50 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
13f60 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
13f70 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
13f80 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
13f90 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
13fa0 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
13fb0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
13fc0 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
13fd0 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
13fe0 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
13ff0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
14000 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
14010 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
14020 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
14030 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
14040 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
14050 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
14060 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
14070 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
14080 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
14090 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
140a0 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
140b0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
140c0 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
140d0 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
140e0 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
140f0 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
14100 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
14110 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
14120 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
14130 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
14140 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
14150 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
14160 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
14170 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
14180 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
14190 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
141a0 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
141b0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
141c0 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
141d0 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
141e0 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
141f0 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
14200 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
14210 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
14220 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
14230 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
14240 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
14250 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
14260 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
14270 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
14280 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
14290 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
142a0 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
142b0 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
142c0 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
142d0 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
142e0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
142f0 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
14300 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
14310 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
14320 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
14330 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
14340 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
14350 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
14360 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
14370 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
14380 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
14390 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
143a0 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
143b0 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
143c0 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
143d0 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
143e0 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
143f0 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
14400 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
14410 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
14420 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
14430 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
14440 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
14450 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
14460 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
14470 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
14480 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
14490 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
144a0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
144b0 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
144c0 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
144d0 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
144e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
144f0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
14500 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
14510 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
14520 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14530 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
14540 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
14550 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14560 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
14570 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
14580 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
14590 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
145a0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
145b0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
145c0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
145d0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
145e0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
145f0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
14600 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
14610 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
14620 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
14630 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
14640 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
14650 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
14660 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
14670 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
14680 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
14690 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
146a0 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
146b0 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
146c0 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
146d0 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
146e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
146f0 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
14700 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
14710 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14720 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
14730 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14740 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
14750 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
14760 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
14770 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
14780 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
14790 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
147a0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
147b0 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
147c0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
147d0 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
147e0 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
147f0 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
14800 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
14810 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
14820 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
14830 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
14840 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
14850 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
14860 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14870 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
14880 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
14890 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
148a0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
148b0 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
148c0 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
148d0 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
148e0 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
148f0 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
14900 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
14910 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
14920 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
14930 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
14940 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
14950 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
14960 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
14970 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14980 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14990 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
149a0 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
149b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
149c0 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
149d0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
149e0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
149f0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
14a00 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
14a10 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
14a20 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
14a30 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
14a40 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
14a50 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
14a60 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
14a70 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
14a80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
14a90 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
14aa0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
14ab0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
14ac0 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
14ad0 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
14ae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
14af0 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
14b00 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
14b10 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
14b20 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
14b30 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
14b40 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
14b50 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
14b60 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
14b70 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
14b80 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
14b90 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
14ba0 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
14bb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
14bc0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
14bd0 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
14be0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
14bf0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
14c00 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
14c10 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
14c20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14c30 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
14c40 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
14c50 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
14c60 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
14c70 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
14c80 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14c90 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
14ca0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
14cb0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
14cc0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
14cd0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
14ce0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14cf0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
14d00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
14d10 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
14d20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
14d30 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
14d40 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
14d50 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
14d60 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
14d70 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
14d80 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
14d90 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
14da0 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
14db0 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
14dc0 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
14dd0 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
14de0 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
14df0 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
14e00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14e10 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
14e20 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
14e30 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
14e40 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
14e50 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
14e60 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14e70 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
14e80 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
14e90 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
14ea0 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
14eb0 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
14ec0 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
14ed0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
14ee0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
14ef0 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
14f00 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
14f10 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
14f20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
14f30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14f40 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
14f50 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
14f60 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
14f70 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
14f80 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
14f90 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
14fa0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
14fb0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
14fc0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
14fd0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
14fe0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14ff0 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
15000 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
15010 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
15020 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
15030 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
15040 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
15050 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
15060 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
15070 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
15080 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
15090 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
150a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
150b0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
150c0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
150d0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
150e0 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
150f0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
15100 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
15110 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
15120 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
15130 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
15140 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
15150 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
15160 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
15170 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
15180 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
15190 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
151a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
151b0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
151c0 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
151d0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
151e0 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
151f0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
15200 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
15210 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
15220 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
15230 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
15240 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
15250 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
15260 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
15270 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
15280 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
15290 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
152a0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
152b0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
152c0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
152d0 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
152e0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
152f0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15300 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
15310 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
15320 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
15330 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
15340 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
15350 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  e.  The [sqlite3
15360 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
15370 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
15380 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
15390 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
153a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
153b0 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
153c0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
153d0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
153e0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
153f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15400 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
15410 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
15420 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
15430 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15440 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
15450 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
15460 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
15470 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
15480 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
15490 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
154a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
154b0 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
154c0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
154d0 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
154e0 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
154f0 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  , interpreted as
15500 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20   a .** boolean, 
15510 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
15520 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
15530 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f  llection of memo
15540 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a  ry allocation .*
15550 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  * statistics. ^(
15560 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
15570 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
15580 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20  s are disabled, 
15590 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  the .** followin
155a0 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
155b0 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
155c0 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
155d0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
155e0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
155f0 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
15600 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
15610 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
15620 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
15630 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
15640 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
15650 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
15660 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
15670 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
15680 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
15690 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
156a0 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
156b0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
156c0 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
156d0 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
156e0 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
156f0 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
15700 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
15710 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
15720 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
15730 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
15740 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
15750 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
15760 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
15770 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
15780 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
15790 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
157a0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
157b0 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
157c0 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
157d0 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
157e0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
157f0 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  ts:  A pointer a
15800 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
15810 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
15820 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
15830 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
15840 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
15850 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
15860 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
15870 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
15880 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
15890 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
158a0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
158b0 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
158c0 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
158d0 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
158e0 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73   16..** The firs
158f0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
15900 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
15910 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
15920 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
15930 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
15940 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
15950 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
15960 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74  e no more than t
15970 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65  wo scratch buffe
15980 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20  rs per thread.  
15990 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62  So.** N should b
159a0 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74  e set to twice t
159b0 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
159c0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
159d0 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  reads..** ^SQLit
159e0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
159f0 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62  uire a scratch b
15a00 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
15a10 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
15a20 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
15a30 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53  page size. ^If S
15a40 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
15a50 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
15a60 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
15a70 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
15a80 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
15a90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15aa0 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
15ab0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
15ac0 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
15ad0 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
15ae0 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a  ry needed.</dd>.
15af0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15b00 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
15b10 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15b20 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
15b30 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
15b40 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
15b50 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
15b60 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
15b70 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
15b80 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
15b90 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
15ba0 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
15bb0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
15bc0 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
15bd0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
15be0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
15bf0 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  ed if an applica
15c00 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
15c10 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
15c20 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
15c30 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c  ed using the SQL
15c40 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15c50 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  E2 option..** Th
15c60 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
15c70 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
15c80 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
15c90 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
15ca0 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
15cb0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
15cc0 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
15cd0 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
15ce0 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
15cf0 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
15d00 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
15d10 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
15d20 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
15d30 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
15d40 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
15d50 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
15d60 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
15d70 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
15d80 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
15d90 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
15da0 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
15db0 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
15dc0 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
15dd0 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
15de0 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
15df0 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
15e00 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
15e10 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
15e20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
15e30 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
15e40 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
15e50 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
15e60 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
15e70 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
15e80 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
15e90 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
15ea0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
15eb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
15ec0 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
15ed0 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
15ee0 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
15ef0 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
15f00 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
15f10 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
15f20 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
15f30 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
15f40 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
15f50 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
15f60 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
15f70 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
15f80 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
15f90 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
15fa0 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
15fb0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  * The pointer in
15fc0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
15fd0 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
15fe0 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
15ff0 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
16000 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
16010 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
16020 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
16030 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
16040 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
16050 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
16060 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
16070 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
16080 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
16090 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
160a0 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
160b0 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
160c0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
160d0 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
160e0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62  location needs b
160f0 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
16100 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b  ided.** for by [
16110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
16120 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49  RATCH] and [SQLI
16130 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
16140 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61  CHE]..** There a
16150 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
16160 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  ts: An 8-byte al
16170 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
16180 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
16190 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
161a0 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
161b0 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
161c0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
161d0 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
161e0 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
161f0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
16200 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
16210 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
16220 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
16230 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
16240 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
16250 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
16260 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
16270 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
16280 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
16290 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
162a0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
162b0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
162c0 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
162d0 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65  t NULL and eithe
162e0 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
162f0 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20  _MEMSYS3] or.** 
16300 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
16310 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69  EMSYS5] are defi
16320 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c  ned, then the al
16330 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
16340 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
16350 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
16360 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
16370 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
16380 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
16390 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
163a0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
163b0 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
163c0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
163d0 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
163e0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
163f0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
16400 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
16410 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
16420 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
16430 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
16440 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
16450 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
16460 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
16470 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
16480 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
16490 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
164a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
164b0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
164c0 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
164d0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
164e0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
164f0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
16500 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
16510 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
16520 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
16530 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
16540 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
16550 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
16560 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
16570 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
16580 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
16590 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
165a0 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72  e.** the mutex r
165b0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
165c0 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
165d0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
165e0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e  py of the.** con
165f0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
16600 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
16610 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
16620 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
16630 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
16640 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
16650 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
16660 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
16670 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
16680 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
16690 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
166a0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
166b0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
166c0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
166d0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
166e0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
166f0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
16700 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
16710 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
16720 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16730 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
16740 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
16750 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
16760 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
16770 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16780 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d  ONFIG_GETMUTEX]]
16790 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
167a0 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
167b0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
167c0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
167d0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
167e0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
167f0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
16800 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
16810 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
16820 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
16830 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
16840 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
16850 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
16860 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
16870 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
16880 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
16890 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
168a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
168b0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
168c0 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
168d0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
168e0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
168f0 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
16900 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
16910 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
16920 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
16930 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
16940 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
16950 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
16960 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
16970 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
16980 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
16990 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
169a0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
169b0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
169c0 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
169d0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
169e0 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
169f0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
16a00 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
16a10 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
16a20 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
16a30 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16a40 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
16a50 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
16a60 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16a70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
16a80 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
16a90 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16aa0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
16ab0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
16ac0 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
16ad0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
16ae0 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a  e the default.**
16af0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16b00 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61  on for the looka
16b10 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
16b20 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a  cator on each.**
16b30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16b40 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72  ction].  The fir
16b50 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
16b60 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
16b70 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
16b80 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
16b90 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
16ba0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
16bb0 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
16bc0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
16bd0 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68  nection.)^  ^(Th
16be0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
16bf0 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74  he.** <i>default
16c00 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
16c10 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
16c20 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
16c30 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20  IDE].** verb to 
16c40 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
16c50 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
16c60 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
16c70 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
16c80 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
16c90 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
16ca0 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
16cb0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16cc0 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
16cd0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16ce0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
16cf0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
16d00 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
16d10 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
16d20 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16d30 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
16d40 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
16d50 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
16d60 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20  bject specifies 
16d70 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
16d80 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
16d90 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
16da0 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69  tation.)^  ^SQLi
16db0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
16dc0 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74  of the.** object
16dd0 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72   and uses it for
16de0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
16df0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c  ry allocations.<
16e00 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16e10 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16e20 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
16e30 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
16e40 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
16e50 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
16e60 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
16e70 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
16e80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16e90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
16ea0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
16eb0 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
16ec0 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
16ed0 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
16ee0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
16ef0 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
16f00 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
16f10 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16f20 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
16f30 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
16f40 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
16f50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
16f60 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
16f70 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
16f80 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
16f90 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
16fa0 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
16fb0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
16fc0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
16fd0 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
16fe0 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
16ff0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
17000 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
17010 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
17020 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
17030 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
17040 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
17050 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
17060 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
17070 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
17080 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
17090 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
170a0 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
170b0 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
170c0 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
170d0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
170e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
170f0 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
17100 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
17110 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
17120 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
17130 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
17140 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
17150 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
17160 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
17170 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17180 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
17190 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
171a0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
171b0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
171c0 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
171d0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
171e0 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
171f0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
17200 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
17210 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
17220 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
17230 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
17240 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
17250 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
17260 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
17270 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
17280 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
17290 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
172a0 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
172b0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
172c0 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
172d0 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
172e0 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
172f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
17300 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
17310 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
17320 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
17330 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
17340 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
17350 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
17360 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
17370 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
17380 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
17390 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
173a0 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53  NFIG_URI]] <dt>S
173b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
173c0 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70  .** <dd> This op
173d0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
173e0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
173f0 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e  type int. If non
17400 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55  -zero, then.** U
17410 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
17420 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e  lobally enabled.
17430 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
17440 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  r is zero, then 
17450 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20  URI handling.** 
17460 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
17470 62 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61 6e  bled. If URI han
17480 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
17490 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66  y enabled, all f
174a0 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73  ilenames.** pass
174b0 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ed to [sqlite3_o
174c0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
174d0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71  _open_v2()], [sq
174e0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
174f0 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  or.** specified 
17500 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41  as part of [ATTA
17510 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65  CH] commands are
17520 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
17530 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73  URIs, regardless
17540 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f  .** of whether o
17550 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
17560 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
17570 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
17580 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
17590 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
175a0 64 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f 62  d. If it is glob
175b0 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
175c0 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
175d0 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
175e0 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
175f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
17600 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
17610 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
17620 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
17630 70 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75 6c  pened. By defaul
17640 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
17650 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
17660 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
17670 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
17680 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
17690 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
176a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
176b0 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
176c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ed..**.** [[SQLI
176d0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
176e0 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
176f0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
17700 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17710 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
17720 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17730 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
17740 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
17750 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
17760 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
17770 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
17780 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
17790 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
177a0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
177b0 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
177c0 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  s..** </dl>.*/.#
177d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
177e0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
177f0 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
17800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17810 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
17820 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
17830 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17840 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
17850 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
17860 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17870 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
17880 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
17890 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
178a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
178b0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
178c0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
178d0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
178e0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
178f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
17900 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
17910 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
17920 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
17930 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
17940 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
17950 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
17960 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
17970 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17980 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
17990 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
179a0 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
179b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
179c0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
179d0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
179e0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
179f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
17a00 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
17a10 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
17a20 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
17a30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17a40 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
17a50 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
17a60 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
17a70 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
17a80 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
17a90 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
17aa0 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
17ab0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17ac0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17ad0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
17ae0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
17af0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17b00 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
17b10 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
17b20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
17b30 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
17b40 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
17b50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17b60 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
17b70 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
17b80 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
17b90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
17ba0 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
17bb0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
17bc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17bd0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
17be0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
17bf0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
17c00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17c10 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
17c20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
17c30 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
17c40 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
17c50 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
17c60 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
17c70 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
17c80 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
17c90 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
17ca0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
17cb0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
17cc0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
17cd0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
17ce0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
17cf0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
17d00 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
17d10 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
17d20 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
17d30 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
17d40 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
17d50 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
17d60 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
17d70 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
17d80 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
17d90 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
17da0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
17db0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
17dc0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
17dd0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17de0 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
17df0 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
17e00 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
17e10 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
17e20 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
17e30 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
17e40 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
17e50 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
17e60 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
17e70 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
17e80 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
17e90 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
17ea0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
17eb0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17ec0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
17ed0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
17ee0 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
17ef0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
17f00 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
17f10 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
17f20 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
17f30 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
17f40 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
17f50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17f60 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
17f70 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
17f80 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
17f90 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
17fa0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
17fb0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
17fc0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
17fd0 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
17fe0 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
17ff0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18000 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
18010 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
18020 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
18030 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
18040 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
18050 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
18060 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
18070 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
18080 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
18090 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
180a0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
180b0 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
180c0 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
180d0 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
180e0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
180f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
18100 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
18110 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
18120 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
18130 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
18140 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
18150 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
18160 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
18170 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
18180 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
18190 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
181a0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
181b0 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
181c0 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
181d0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
181e0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
181f0 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
18200 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
18210 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
18220 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
18230 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
18240 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
18250 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
18260 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
18270 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
18280 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
18290 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
182a0 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
182b0 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
182c0 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
182d0 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
182e0 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
182f0 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
18300 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
18310 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
18320 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
18330 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
18340 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
18350 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
18360 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
18370 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
18380 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
18390 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
183a0 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
183b0 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
183c0 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
183d0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
183e0 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
183f0 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
18400 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
18410 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
18420 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18430 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
18440 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
18450 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
18460 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
18470 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
18480 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
18490 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
184a0 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
184b0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
184c0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
184d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
184e0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
184f0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
18500 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
18510 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
18520 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
18530 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
18540 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
18550 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
18560 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
18570 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18580 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
18590 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
185a0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
185b0 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
185c0 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
185d0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
185e0 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
185f0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
18600 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
18610 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
18620 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
18630 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
18640 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
18650 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
18660 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
18670 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
18680 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
18690 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
186a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
186b0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
186c0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
186d0 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
186e0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
186f0 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
18700 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
18710 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
18720 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
18730 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
18740 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
18750 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
18760 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
18770 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
18780 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
18790 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
187a0 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
187b0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
187c0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
187d0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
187e0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
187f0 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
18800 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
18810 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
18820 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
18830 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
18840 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
18850 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
18860 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
18870 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
18880 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
18890 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
188a0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
188b0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
188c0 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
188d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
188e0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
188f0 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
18900 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
18910 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18920 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
18930 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
18940 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
18950 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
18960 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
18970 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
18980 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
18990 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
189a0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
189b0 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
189c0 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  des.**.** ^The s
189d0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
189e0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
189f0 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
18a00 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
18a10 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
18a20 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
18a30 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
18a40 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
18a50 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
18a60 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
18a70 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
18a80 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
18a90 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
18aa0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
18ab0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
18ac0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
18ad0 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
18ae0 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
18af0 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20  ert Rowid.**.** 
18b00 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61  ^Each entry in a
18b10 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68  n SQLite table h
18b20 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
18b30 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
18b40 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
18b50 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
18b60 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
18b70 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
18b80 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
18b90 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
18ba0 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
18bb0 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
18bc0 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
18bd0 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
18be0 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
18bf0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
18c00 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
18c10 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
18c20 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
18c30 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
18c40 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
18c50 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
18c60 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
18c70 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
18c80 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
18c90 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
18ca0 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  ] of the most re
18cb0 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
18cc0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
18cd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
18ce0 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  om the [database
18cf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
18d00 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
18d10 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53  ument.  ^As of S
18d20 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
18d30 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  7.7, this routin
18d40 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68  es.** records th
18d50 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f  e last insert ro
18d60 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69  wid of both ordi
18d70 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20  nary tables and 
18d80 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
18d90 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63  ..** ^If no succ
18da0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
18db0 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63  .** have ever oc
18dc0 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64  curred on that d
18dd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18de0 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75  on, zero is retu
18df0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  rned..**.** ^(If
18e00 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
18e10 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
18e20 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61  gger or within a
18e30 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
18e40 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  .** method, then
18e50 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
18e60 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72  ll return the [r
18e70 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
18e80 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20  erted.** row as 
18e90 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
18ea0 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
18eb0 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72  able method is r
18ec0 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
18ed0 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
18ee0 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
18ef0 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68   method ends, th
18f00 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
18f10 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
18f20 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
18f30 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
18f40 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  re the trigger o
18f50 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  r virtual.** tab
18f60 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e  le method began.
18f70 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
18f80 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
18f90 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
18fa0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
18fb0 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
18fc0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
18fd0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
18fe0 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
18ff0 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
19000 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
19010 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
19020 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
19030 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
19040 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
19050 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
19060 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
19070 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
19080 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
19090 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
190a0 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
190b0 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
190c0 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
190d0 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
190e0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
190f0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
19100 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
19110 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
19120 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
19130 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
19140 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
19150 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
19160 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
19170 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
19180 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
19190 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
191a0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
191b0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
191c0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
191d0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
191e0 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
191f0 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
19200 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
19210 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
19220 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
19230 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
19240 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
19250 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
19260 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
19270 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
19280 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
19290 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
192a0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
192b0 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
192c0 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
192d0 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
192e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
192f0 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
19300 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19310 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
19320 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
19330 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
19340 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
19350 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
19360 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19370 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
19380 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
19390 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
193a0 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
193b0 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
193c0 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
193d0 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
193e0 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53  rt [rowid]..*/.S
193f0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
19400 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
19410 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19420 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
19430 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
19440 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
19450 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
19460 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
19470 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
19480 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
19490 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
194a0 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
194b0 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
194c0 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
194d0 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
194e0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
194f0 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74  t.** on the [dat
19500 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19510 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  ] specified by t
19520 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
19530 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68  er..** ^(Only ch
19540 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
19550 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
19560 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
19570 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
19580 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
19590 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
195a0 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
195b0 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
195c0 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b  ** triggers or [
195d0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
195e0 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ons] are not cou
195f0 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a  nted.)^ Use the.
19600 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  ** [sqlite3_tota
19610 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
19620 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68  ction to find th
19630 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
19640 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63  f changes.** inc
19650 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
19660 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
19670 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65  s and foreign ke
19680 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  y actions..**.**
19690 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
196a0 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
196b0 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
196c0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
196d0 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
196e0 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
196f0 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
19700 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
19710 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67  * ^(A "row chang
19720 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74  e" is a change t
19730 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a single row o
19740 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  f a single table
19750 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e  .** caused by an
19760 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c   INSERT, DELETE,
19770 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65   or UPDATE state
19780 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74  ment.  Rows that
19790 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20  .** are changed 
197a0 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20  as side effects 
197b0 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  of [REPLACE] con
197c0 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
197d0 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c  on,.** rollback,
197e0 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
197f0 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c  g, [DROP TABLE],
19800 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72   or by any other
19810 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64  .** mechanisms d
19820 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64  o not count as d
19830 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
19840 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  s.)^.**.** A "tr
19850 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
19860 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
19870 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
19880 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
19890 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
198a0 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47  f a [CREATE TRIG
198b0 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20  GER | trigger]. 
198c0 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  .** Most SQL sta
198d0 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
198e0 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
198f0 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
19900 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
19910 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
19920 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
19930 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
19940 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
19950 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
19960 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
19970 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
19980 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
19990 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
199a0 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
199b0 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
199c0 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
199d0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  ation..**.** ^Ca
199e0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
199f0 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
19a00 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
19a10 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e  sively does.** n
19a20 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  ot create a new 
19a30 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
19a40 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
19a50 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
19a60 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
19a70 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
19a80 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
19a90 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
19aa0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
19ab0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
19ac0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
19ad0 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
19ae0 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63  ** ^Thus, when c
19af0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
19b00 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
19b10 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
19b20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
19b30 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
19b40 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
19b50 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
19b60 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
19b70 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
19b80 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e  he top level.  ^
19b90 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79  (Within the body
19ba0 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
19bb0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
19bc0 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
19bd0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
19be0 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
19bf0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
19c00 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
19c10 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
19c20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
19c30 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
19c40 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
19c50 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
19c60 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
19c70 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
19c80 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
19c90 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
19ca0 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
19cb0 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
19cc0 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
19cd0 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
19ce0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
19cf0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
19d00 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
19d10 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
19d20 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
19d30 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
19d40 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
19d50 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
19d60 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
19d70 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
19d80 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
19d90 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19da0 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
19db0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
19dc0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
19dd0 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
19de0 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
19df0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
19e00 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
19e10 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
19e20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
19e30 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
19e40 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
19e50 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
19e60 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
19e70 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
19e80 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
19e90 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
19ea0 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45   caused by [INSE
19eb0 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d  RT],.** [UPDATE]
19ec0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
19ed0 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68  tements since th
19ee0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
19ef0 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e  ection] was open
19f00 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75  ed..** ^(The cou
19f10 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  nt returned by s
19f20 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
19f30 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20  nges() includes 
19f40 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66  all changes.** f
19f50 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20  rom all [CREATE 
19f60 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
19f70 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20  r] contexts and 
19f80 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a  changes made by.
19f90 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
19fa0 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65  actions]. Howeve
19fb0 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20  r,.** the count 
19fc0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
19fd0 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f   changes used to
19fe0 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c   implement [REPL
19ff0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73  ACE] constraints
1a000 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  ,.** do rollback
1a010 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
1a020 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20  ssing, or [DROP 
1a030 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e  TABLE] processin
1a040 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74  g.  The.** count
1a050 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1a060 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20  e rows of views 
1a070 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e  that fire an [IN
1a080 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
1a090 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20  ],.** though if 
1a0a0 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74  the INSTEAD OF t
1a0b0 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61  rigger makes cha
1a0c0 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c  nges of its own,
1a0d0 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a   those changes .
1a0e0 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29  ** are counted.)
1a0f0 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ^.** ^The sqlite
1a100 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1a110 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74  ) function count
1a120 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73  s the changes as
1a130 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20   soon as.** the 
1a140 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
1a150 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d  akes them is com
1a160 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65  pleted (when the
1a170 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   statement handl
1a180 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74  e.** is passed t
1a190 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
1a1a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1a1b0 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a  finalize()])..**
1a1c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
1a1d0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
1a1e0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
1a1f0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
1a200 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
1a210 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
1a220 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1a230 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
1a240 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1a250 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
1a260 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
1a270 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1a280 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
1a290 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1a2a0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1a2b0 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
1a2c0 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
1a2d0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1a2e0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
1a2f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1a300 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1a310 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1a320 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a330 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
1a340 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
1a350 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1a360 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
1a370 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
1a380 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
1a390 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
1a3a0 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
1a3b0 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
1a3c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
1a3d0 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
1a3e0 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
1a3f0 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
1a400 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
1a410 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
1a420 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
1a430 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
1a440 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
1a450 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
1a460 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
1a470 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
1a480 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
1a490 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
1a4a0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
1a4b0 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
1a4c0 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
1a4d0 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
1a4e0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
1a4f0 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
1a500 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
1a510 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1a520 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1a530 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
1a540 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
1a550 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
1a560 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1a570 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
1a580 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
1a590 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
1a5a0 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
1a5b0 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
1a5c0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
1a5d0 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
1a5e0 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
1a5f0 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
1a600 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
1a610 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
1a620 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
1a630 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
1a640 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
1a650 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
1a660 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
1a670 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
1a680 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
1a690 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
1a6a0 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
1a6b0 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
1a6c0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
1a6d0 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
1a6e0 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
1a6f0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
1a700 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
1a710 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
1a720 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
1a730 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
1a740 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1a750 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
1a760 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
1a770 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
1a780 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
1a790 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
1a7a0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
1a7b0 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
1a7c0 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
1a7d0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1a7e0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1a7f0 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
1a800 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
1a810 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
1a820 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
1a830 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
1a840 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
1a850 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
1a860 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
1a870 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
1a880 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1a890 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
1a8a0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
1a8b0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1a8c0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1a8d0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
1a8e0 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
1a8f0 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
1a900 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
1a910 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1a920 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
1a930 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
1a940 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
1a950 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
1a960 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
1a970 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1a980 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
1a990 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
1a9a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1a9b0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1a9c0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1a9d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1a9e0 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
1a9f0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  *.** If the data
1aa00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1aa10 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71  closes while [sq
1aa20 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1aa30 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  )].** is running
1aa40 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
1aa50 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
1aa60 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  pen..*/.SQLITE_A
1aa70 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
1aa80 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
1aa90 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1aaa0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
1aab0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
1aac0 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
1aad0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1aae0 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
1aaf0 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
1ab00 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
1ab10 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
1ab20 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
1ab30 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
1ab40 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
1ab50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
1ab60 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
1ab70 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
1ab80 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
1ab90 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
1aba0 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
1abb0 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
1abc0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
1abd0 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
1abe0 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
1abf0 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
1ac00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
1ac10 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
1ac20 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
1ac30 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
1ac40 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
1ac50 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
1ac60 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
1ac70 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
1ac80 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
1ac90 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
1aca0 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
1acb0 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
1acc0 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
1acd0 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
1ace0 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
1acf0 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
1ad00 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
1ad10 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
1ad20 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
1ad30 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
1ad40 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
1ad50 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
1ad60 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
1ad70 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
1ad80 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
1ad90 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
1ada0 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
1adb0 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
1adc0 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
1add0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
1ade0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
1adf0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
1ae00 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
1ae10 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
1ae20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
1ae30 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
1ae40 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
1ae50 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
1ae60 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
1ae70 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
1ae80 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
1ae90 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
1aea0 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
1aeb0 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
1aec0 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
1aed0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
1aee0 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
1aef0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
1af00 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
1af10 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
1af20 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1af30 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
1af40 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
1af50 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
1af60 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
1af70 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
1af80 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
1af90 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
1afa0 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
1afb0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
1afc0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1afd0 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
1afe0 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
1aff0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
1b000 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
1b010 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
1b020 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
1b030 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
1b040 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
1b050 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1b060 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
1b070 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
1b080 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1b090 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
1b0a0 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
1b0b0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
1b0c0 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
1b0d0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
1b0e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1b0f0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b100 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
1b110 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
1b120 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
1b130 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
1b140 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
1b150 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
1b160 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
1b170 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
1b180 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e  Y Errors.**.** ^
1b190 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
1b1a0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
1b1b0 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
1b1c0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
1b1d0 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
1b1e0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
1b1f0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
1b200 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
1b210 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
1b220 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
1b230 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1b240 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
1b250 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
1b260 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
1b270 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
1b280 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
1b290 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
1b2a0 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
1b2b0 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
1b2c0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
1b2d0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
1b2e0 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
1b2f0 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
1b300 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
1b310 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
1b320 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1b330 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
1b340 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
1b350 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
1b360 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
1b370 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
1b380 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1b390 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
1b3a0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
1b3b0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
1b3c0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
1b3d0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
1b3e0 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
1b3f0 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
1b400 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
1b410 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
1b420 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
1b430 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
1b440 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1b450 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
1b460 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
1b470 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
1b480 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1b490 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
1b4a0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
1b4b0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
1b4c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
1b4d0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
1b4e0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1b4f0 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
1b500 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
1b510 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
1b520 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
1b530 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  ng and the cycle
1b540 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
1b550 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
1b560 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
1b570 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
1b580 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
1b590 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
1b5a0 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
1b5b0 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
1b5c0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
1b5d0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
1b5e0 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
1b5f0 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
1b600 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
1b610 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
1b620 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
1b630 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
1b640 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
1b650 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
1b660 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
1b670 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
1b680 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
1b690 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
1b6a0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
1b6b0 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
1b6c0 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
1b6d0 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
1b6e0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1b6f0 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
1b700 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1b710 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
1b720 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
1b730 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
1b740 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
1b750 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
1b760 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
1b770 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
1b780 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1b790 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
1b7a0 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
1b7b0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
1b7c0 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
1b7d0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1b7e0 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
1b7f0 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
1b800 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
1b810 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
1b820 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
1b830 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
1b840 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
1b850 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
1b860 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
1b870 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1b880 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
1b890 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
1b8a0 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
1b8b0 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
1b8c0 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
1b8d0 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
1b8e0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
1b8f0 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
1b900 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
1b910 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1b920 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  L..**.** ^The [S
1b930 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
1b940 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
1b950 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
1b960 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e  BLOCKED].** when
1b970 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
1b980 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
1b990 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
1b9a0 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
1b9b0 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
1b9c0 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
1b9d0 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
1b9e0 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
1b9f0 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
1ba00 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
1ba10 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
1ba20 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
1ba30 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
1ba40 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
1ba50 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
1ba60 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
1ba70 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
1ba80 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1ba90 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
1baa0 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
1bab0 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69  aders.  ^If it i
1bac0 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
1bad0 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
1bae0 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
1baf0 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
1bb00 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
1bb10 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
1bb20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
1bb30 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
1bb40 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
1bb50 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
1bb60 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
1bb70 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
1bb80 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
1bb90 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68  R_BLOCKED].  ^Th
1bba0 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
1bbb0 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
1bbc0 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
1bbd0 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
1bbe0 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65  hanges.  See the
1bbf0 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76  .** <a href="/cv
1bc00 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
1bc10 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
1bc20 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
1bc30 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
1bc40 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
1bc50 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
1bc60 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
1bc70 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
1bc80 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ortant..**.** ^(
1bc90 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1bca0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1bcb0 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
1bcc0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
1bcd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bce0 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
1bcf0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
1bd00 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
1bd10 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
1bd20 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
1bd30 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
1bd40 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1bd50 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f  ()].** will also
1bd60 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68   set or clear th
1bd70 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1bd80 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
1bd90 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
1bda0 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
1bdb0 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
1bdc0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1bdd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1bde0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1bdf0 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20  y handler.  Any 
1be00 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1be10 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1be20 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1be30 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1be40 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1be50 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1be60 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1be70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1be80 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1be90 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1bea0 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ler..*/.SQLITE_A
1beb0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
1bec0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1bed0 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
1bee0 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
1bef0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1bf00 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
1bf10 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
1bf20 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1bf30 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1bf40 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1bf50 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1bf60 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1bf70 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1bf80 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1bf90 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1bfa0 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1bfb0 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1bfc0 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1bfd0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1bfe0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1bff0 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1c000 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1c010 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1c020 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1c030 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1c040 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1c050 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1c060 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1c070 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1c080 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
1c090 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
1c0a0 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  KED]..**.** ^Cal
1c0b0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
1c0c0 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
1c0d0 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
1c0e0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
1c0f0 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
1c100 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
1c110 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1c120 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1c130 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
1c140 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
1c150 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1c160 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
1c170 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
1c180 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
1c190 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
1c1a0 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
1c1b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1c1c0 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
1c1d0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
1c1e0 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
1c1f0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1c200 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
1c210 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1c220 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
1c230 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
1c240 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
1c250 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
1c260 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
1c270 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
1c280 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ies.**.** This i
1c290 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
1c2a0 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
1c2b0 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
1c2c0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1c2d0 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
1c2e0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1c2f0 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
1c300 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
1c310 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
1c320 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
1c330 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
1c340 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
1c350 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1c360 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
1c370 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
1c380 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
1c390 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
1c3a0 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
1c3b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
1c3c0 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
1c3d0 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
1c3e0 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
1c3f0 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
1c400 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
1c410 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
1c420 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
1c430 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
1c440 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
1c450 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
1c460 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
1c470 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
1c480 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
1c490 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
1c4a0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
1c4b0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1c4c0 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
1c4d0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
1c4e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1c4f0 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
1c500 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
1c510 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
1c520 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
1c530 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
1c540 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
1c550 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1c560 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
1c570 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
1c580 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
1c590 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
1c5a0 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
1c5b0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
1c5c0 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
1c5d0 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
1c5e0 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
1c5f0 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
1c600 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
1c610 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1c620 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
1c630 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
1c640 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
1c650 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
1c660 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1c670 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
1c680 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
1c690 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1c6a0 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
1c6b0 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
1c6c0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
1c6d0 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
1c6e0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
1c6f0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
1c700 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
1c710 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1c720 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1c730 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
1c740 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
1c750 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
1c760 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
1c770 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
1c780 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1c790 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1c7a0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
1c7b0 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
1c7c0 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
1c7d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1c7e0 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
1c7f0 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
1c800 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
1c810 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
1c820 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
1c830 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
1c840 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1c850 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
1c860 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
1c870 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
1c880 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
1c890 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
1c8a0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
1c8b0 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
1c8c0 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
1c8d0 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
1c8e0 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
1c8f0 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
1c900 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
1c910 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
1c920 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1c930 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1c940 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
1c950 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1c960 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
1c970 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1c980 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
1c990 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
1c9a0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
1c9b0 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
1c9c0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1c9d0 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
1c9e0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1c9f0 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
1ca00 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1ca10 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
1ca20 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1ca30 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
1ca40 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
1ca50 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1ca60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ca70 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
1ca80 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
1ca90 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
1caa0 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
1cab0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1cac0 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
1cad0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
1cae0 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
1caf0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1cb00 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1cb10 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1cb20 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1cb30 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1cb40 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1cb50 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1cb60 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1cb70 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1cb80 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1cb90 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1cba0 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1cbb0 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1cbc0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1cbd0 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1cbe0 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1cbf0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1cc00 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1cc10 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1cc20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1cc30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1cc40 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1cc50 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1cc60 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1cc70 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1cc80 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1cc90 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1cca0 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1ccb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1ccc0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1ccd0 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1cce0 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1ccf0 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1cd00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1cd10 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1cd20 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1cd30 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1cd40 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1cd50 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1cd60 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1cd70 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1cd80 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1cd90 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1cda0 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1cdb0 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1cdc0 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1cdd0 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1cde0 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1cdf0 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1ce00 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1ce10 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1ce20 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1ce30 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1ce40 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1ce50 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1ce60 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1ce70 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1ce80 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1ce90 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1cea0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1ceb0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  rrmsg()]..*/.SQL
1cec0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1ced0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1cee0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1cef0 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1cf00 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1cf10 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1cf20 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1cf30 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1cf40 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1cf50 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1cf60 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1cf70 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1cf80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1cf90 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1cfa0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1cfb0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1cfc0 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1cfd0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1cfe0 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1cff0 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1d000 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1d010 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1d020 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1d030 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1d040 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1d050 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
1d060 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d070 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
1d080 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
1d090 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1d0a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1d0b0 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
1d0c0 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
1d0d0 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
1d0e0 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
1d0f0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1d100 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
1d110 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
1d120 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
1d130 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
1d140 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
1d150 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
1d160 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
1d170 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1d180 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
1d190 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1d1a0 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
1d1b0 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
1d1c0 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
1d1d0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
1d1e0 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
1d1f0 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
1d200 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
1d210 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
1d220 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1d230 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
1d240 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1d250 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
1d260 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1d270 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1d280 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
1d290 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
1d2a0 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
1d2b0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1d2c0 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
1d2d0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
1d2e0 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
1d2f0 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
1d300 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
1d310 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
1d320 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
1d330 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
1d340 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
1d350 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
1d360 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
1d370 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
1d380 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
1d390 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
1d3a0 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
1d3b0 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
1d3c0 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
1d3d0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
1d3e0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1d3f0 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
1d400 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
1d410 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
1d420 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1d430 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
1d440 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
1d450 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
1d460 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
1d470 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
1d480 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
1d490 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
1d4a0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
1d4b0 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
1d4c0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
1d4d0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
1d4e0 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
1d4f0 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
1d500 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
1d510 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1d520 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
1d530 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
1d540 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
1d550 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
1d560 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
1d570 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
1d580 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1d590 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
1d5a0 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
1d5b0 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
1d5c0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
1d5d0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
1d5e0 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
1d5f0 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
1d600 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
1d610 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
1d620 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
1d630 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
1d640 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
1d650 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
1d660 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
1d670 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
1d680 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
1d690 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
1d6a0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1d6b0 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
1d6c0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1d6d0 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  rintf()..**.** T
1d6e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
1d6f0 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
1d700 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
1d710 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
1d720 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
1d730 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
1d740 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
1d750 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
1d760 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
1d770 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1d780 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
1d790 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
1d7a0 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
1d7b0 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
1d7c0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
1d7d0 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
1d7e0 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
1d7f0 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
1d800 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
1d810 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
1d820 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
1d830 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
1d840 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
1d850 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
1d860 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
1d870 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
1d880 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1d890 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
1d8a0 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
1d8b0 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
1d8c0 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
1d8d0 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
1d8e0 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
1d8f0 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
1d900 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
1d910 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
1d920 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
1d930 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
1d940 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
1d950 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1d960 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1d970 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
1d980 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
1d990 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1d9a0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
1d9b0 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
1d9c0 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
1d9d0 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
1d9e0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1d9f0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1da00 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1da10 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1da20 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1da30 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
1da40 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1da50 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1da60 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1da70 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1da80 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1da90 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1daa0 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
1dab0 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
1dac0 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
1dad0 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
1dae0 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
1daf0 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
1db00 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
1db10 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1db20 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1db30 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1db40 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
1db50 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1db60 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1db70 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1db80 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
1db90 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
1dba0 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
1dbb0 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
1dbc0 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
1dbd0 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
1dbe0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1dbf0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1dc00 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1dc10 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
1dc20 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
1dc30 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1dc40 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
1dc50 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
1dc60 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
1dc70 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
1dc80 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
1dc90 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
1dca0 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
1dcb0 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
1dcc0 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
1dcd0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
1dce0 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
1dcf0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
1dd00 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
1dd10 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
1dd20 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
1dd30 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1dd40 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
1dd50 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
1dd60 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
1dd70 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
1dd80 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
1dd90 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
1dda0 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
1ddb0 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
1ddc0 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
1ddd0 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
1dde0 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
1ddf0 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
1de00 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1de10 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1de20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1de30 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1de40 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
1de50 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1de60 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1de70 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1de80 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1de90 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1dea0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1deb0 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
1dec0 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
1ded0 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
1dee0 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
1def0 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
1df00 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
1df10 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
1df20 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1df30 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
1df40 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
1df50 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
1df60 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
1df70 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
1df80 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
1df90 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
1dfa0 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
1dfb0 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
1dfc0 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
1dfd0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
1dfe0 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53  t string.)^.*/.S
1dff0 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1e000 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1e010 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
1e020 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1e030 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
1e040 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1e050 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54   va_list);.SQLIT
1e060 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1e070 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
1e080 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1e090 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  r*, ...);.SQLITE
1e0a0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1e0b0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1e0c0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1e0d0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1e0e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1e0f0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1e100 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1e110 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1e120 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1e130 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1e140 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1e150 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1e160 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1e170 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1e180 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1e190 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1e1a0 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1e1b0 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1e1c0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1e1d0 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1e1e0 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1e1f0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1e200 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1e210 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1e220 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e230 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1e240 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1e250 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1e260 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1e270 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1e280 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1e290 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1e2a0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1e2b0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1e2c0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1e2d0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1e2e0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1e2f0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1e300 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1e310 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1e320 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1e330 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1e340 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1e350 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1e360 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1e370 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ter..**.** ^Call
1e380 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1e390 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1e3a0 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1e3b0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1e3c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1e3d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e3e0 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1e3f0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1e400 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1e410 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1e420 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1e430 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1e440 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1e450 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1e460 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1e470 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1e480 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1e490 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1e4a0 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1e4b0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1e4c0 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1e4d0 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1e4e0 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1e4f0 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1e500 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1e510 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1e520 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1e530 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1e540 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1e550 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1e560 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1e570 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1e580 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1e590 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1e5a0 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1e5b0 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1e5c0 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1e5d0 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1e5e0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1e5f0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1e600 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1e610 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1e620 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
1e630 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
1e640 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
1e650 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
1e660 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
1e670 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
1e680 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
1e690 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1e6a0 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
1e6b0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
1e6c0 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
1e6d0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1e6e0 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69  r.)^ ^ If the fi
1e6f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1e700 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1e710 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  ().** is a NULL 
1e720 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1e730 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1e740 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1e750 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1e760 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69  loc(N) where N i
1e770 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1e780 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1e790 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
1e7a0 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70  ^If the second p
1e7b0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1e7c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
1e7d0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1e7e0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1e7f0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1e800 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1e810 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1e820 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
1e830 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
1e840 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1e850 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1e860 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
1e870 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  c() returns a po
1e880 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1e890 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1e8a0 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1e8b0 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1e8c0 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e  ULL if sufficien
1e8d0 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76  t memory is unav
1e8e0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1e8f0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1e900 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1e910 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1e920 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1e930 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1e940 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1e950 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1e960 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1e970 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1e980 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
1e990 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
1e9a0 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
1e9b0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1e9c0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1e9d0 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
1e9e0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1e9f0 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
1ea00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ed..**.** ^The m
1ea10 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
1ea20 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1ea30 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
1ea40 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
1ea50 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1ea60 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1ea70 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1ea80 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1ea90 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1eaa0 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1eab0 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1eac0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1ead0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1eae0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1eaf0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1eb00 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1eb10 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1eb20 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1eb30 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1eb40 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1eb50 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1eb60 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1eb70 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1eb80 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1eb90 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1eba0 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1ebb0 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1ebc0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1ebd0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1ebe0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1ebf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64  ..**.** The Wind
1ec00 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1ec10 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   layer calls.** 
1ec20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
1ec30 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
1ec40 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
1ec50 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
1ec60 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
1ec70 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1ec80 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
1ec90 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
1eca0 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
1ecb0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1ecc0 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
1ecd0 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
1ece0 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
1ecf0 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72  cation errors ar
1ed00 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
1ed10 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f  ** they are repo
1ed20 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
1ed30 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
1ed40 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
1ed50 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
1ed60 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
1ed70 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
1ed80 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
1ed90 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1eda0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1edb0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
1edc0 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
1edd0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
1ede0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
1edf0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
1ee00 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1ee10 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
1ee20 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1ee30 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
1ee40 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
1ee50 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
1ee60 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
1ee70 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
1ee80 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
1ee90 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
1eea0 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
1eeb0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
1eec0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1eed0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
1eee0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
1eef0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1ef00 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
1ef10 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  oc(int);.SQLITE_
1ef20 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
1ef30 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
1ef40 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
1ef50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  I void sqlite3_f
1ef60 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
1ef70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1ef80 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
1ef90 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
1efa0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
1efb0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
1efc0 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
1efd0 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
1efe0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
1eff0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
1f000 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
1f010 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1f020 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
1f030 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
1f040 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
1f050 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
1f060 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
1f070 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1f080 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
1f090 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1f0a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1f0b0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
1f0c0 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
1f0d0 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
1f0e0 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
1f0f0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1f100 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1f110 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1f120 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
1f130 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
1f140 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1f150 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
1f160 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1f170 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
1f180 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
1f190 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1f1a0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1f1b0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1f1c0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1f1d0 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
1f1e0 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
1f1f0 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
1f200 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
1f210 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1f220 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
1f230 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
1f240 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
1f250 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
1f260 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
1f270 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
1f280 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
1f290 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
1f2a0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
1f2b0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
1f2c0 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
1f2d0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
1f2e0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1f2f0 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
1f300 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1f310 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
1f320 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1f330 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
1f340 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1f350 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1f360 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1f370 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
1f380 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1f390 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
1f3a0 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  set..*/.SQLITE_A
1f3b0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
1f3c0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1f3d0 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49  used(void);.SQLI
1f3e0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
1f3f0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1f400 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
1f410 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
1f420 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
1f430 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
1f440 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
1f450 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
1f460 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
1f470 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
1f480 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
1f490 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
1f4a0 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
1f4b0 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
1f4c0 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
1f4d0 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
1f4e0 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
1f4f0 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
1f500 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
1f510 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
1f520 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
1f530 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
1f540 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
1f550 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
1f560 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
1f570 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
1f580 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
1f590 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
1f5a0 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
1f5b0 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
1f5c0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
1f5d0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1f5e0 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
1f5f0 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
1f600 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
1f610 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1f620 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e  time this routin
1f630 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69  e is invoked (ei
1f640 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
1f650 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70  or by.** the app
1f660 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52  lication) the PR
1f670 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69  NG is seeded usi
1f680 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
1f690 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74  tained.** from t
1f6a0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
1f6b0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
1f6c0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1f6d0 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f  s] object..** ^O
1f6e0 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  n all subsequent
1f6f0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68   invocations, th
1f700 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
1f710 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
1f720 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
1f730 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
1f740 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
1f750 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
1f760 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
1f770 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1f780 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
1f790 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
1f7a0 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
1f7b0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
1f7c0 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
1f7d0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
1f7e0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1f7f0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
1f800 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f810 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
1f820 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1f830 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
1f840 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
1f850 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
1f860 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1f870 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1f880 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
1f890 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
1f8a0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
1f8b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f8c0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1f8d0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
1f8e0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
1f8f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f900 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
1f910 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1f920 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
1f930 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
1f940 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
1f950 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
1f960 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
1f970 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
1f980 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
1f990 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
1f9a0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1f9b0 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
1f9c0 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
1f9d0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
1f9e0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1f9f0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
1fa00 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
1fa10 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
1fa20 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
1fa30 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
1fa40 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
1fa50 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
1fa60 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
1fa70 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
1fa80 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
1fa90 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
1faa0 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
1fab0 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
1fac0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1fad0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
1fae0 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
1faf0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1fb00 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1fb10 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
1fb20 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1fb30 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
1fb40 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
1fb50 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
1fb60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
1fb70 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1fb80 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1fb90 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
1fba0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
1fbb0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1fbc0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
1fbd0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
1fbe0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1fbf0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
1fc00 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
1fc10 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
1fc20 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
1fc30 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1fc40 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
1fc50 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
1fc60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1fc70 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1fc80 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1fc90 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
1fca0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1fcb0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1fcc0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
1fcd0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
1fce0 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
1fcf0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
1fd00 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1fd10 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1fd20 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
1fd30 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
1fd40 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
1fd50 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1fd60 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
1fd70 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
1fd80 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
1fd90 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1fda0 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
1fdb0 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
1fdc0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
1fdd0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
1fde0 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
1fdf0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
1fe00 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
1fe10 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
1fe20 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
1fe30 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
1fe40 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1fe50 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
1fe60 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
1fe70 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
1fe80 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1fe90 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
1fea0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1feb0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
1fec0 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
1fed0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1fee0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1fef0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
1ff00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1ff10 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
1ff20 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
1ff30 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
1ff40 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
1ff50 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
1ff60 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
1ff70 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
1ff80 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
1ff90 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
1ffa0 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
1ffb0 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
1ffc0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
1ffd0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
1ffe0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
1fff0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
20000 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
20010 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
20020 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
20030 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
20040 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
20050 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
20060 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
20070 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
20080 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
20090 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
200a0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
200b0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
200c0 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
200d0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
200e0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
200f0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
20100 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
20110 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
20120 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
20130 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
20140 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
20150 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
20160 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
20170 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
20180 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
20190 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
201a0 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
201b0 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
201c0 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
201d0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
201e0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
201f0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
20200 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
20210 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
20220 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
20230 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
20240 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
20250 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
20260 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
20270 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
20280 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
20290 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
202a0 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
202b0 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
202c0 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
202d0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
202e0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
202f0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
20300 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
20310 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
20320 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
20330 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
20340 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
20350 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
20360 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
20370 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
20380 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
20390 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
203a0 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
203b0 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
203c0 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
203d0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
203e0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
203f0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
20400 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
20410 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
20420 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
20430 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
20440 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
20450 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
20460 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
20470 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
20480 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
20490 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
204a0 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
204b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
204c0 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
204d0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
204e0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
204f0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
20500 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
20510 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
20520 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
20530 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
20540 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
20550 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
20560 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
20570 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
20580 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20590 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
205a0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
205b0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
205c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
205d0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
205e0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
205f0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
20600 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
20610 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
20620 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
20630 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
20640 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
20650 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
20660 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
20670 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
20680 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
20690 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
206a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
206b0 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
206c0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
206d0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
206e0 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
206f0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
20700 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
20710 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
20720 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
20730 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
20740 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
20750 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
20760 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
20770 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
20780 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
20790 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
207a0 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
207b0 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
207c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
207d0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
207e0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
207f0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
20800 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
20810 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
20820 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
20830 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
20840 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
20850 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20860 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
20870 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
20880 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
20890 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
208a0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
208b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
208c0 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
208d0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
208e0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
208f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
20900 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
20910 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
20920 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
20930 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
20940 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
20950 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
20960 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
20970 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
20980 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
20990 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
209a0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
209b0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
209c0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
209d0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
209e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
209f0 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
20a00 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
20a10 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
20a20 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
20a30 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
20a40 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
20a50 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
20a60 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
20a70 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
20a80 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
20a90 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
20aa0 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
20ab0 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
20ac0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
20ad0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
20ae0 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
20af0 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
20b00 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c  as a [SQLITE_ROL
20b10 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63  LBACK | return c
20b20 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ode].** from the
20b30 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
20b40 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e  n_conflict()] in
20b50 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
20b60 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
20b70 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
20b80 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
20b90 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
20ba0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20bb0 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
20bc0 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
20bd0 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
20be0 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
20bf0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
20c00 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
20c10 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
20c20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
20c30 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
20c40 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
20c50 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
20c60 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
20c70 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
20c80 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
20c90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
20ca0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
20cb0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
20cc0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
20cd0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
20ce0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
20cf0 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
20d00 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
20d10 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
20d20 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
20d30 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
20d40 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
20d50 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
20d60 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
20d70 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
20d80 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
20d90 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
20da0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
20db0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
20dc0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
20dd0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
20de0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
20df0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
20e00 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
20e10 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
20e20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
20e30 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
20e40 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
20e50 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
20e60 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
20e70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
20e80 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
20e90 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
20ea0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
20eb0 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
20ec0 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
20ed0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
20ee0 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
20ef0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
20f00 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
20f10 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
20f20 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
20f30 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
20f40 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
20f50 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
20f60 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
20f70 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
20f80 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
20f90 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
20fa0 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
20fb0 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
20fc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20fd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20fe0 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
20ff0 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
21000 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
21010 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
21020 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
21030 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
21040 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21050 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21060 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
21070 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
21080 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
21090 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
210a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
210b0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
210c0 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
210d0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
210e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
210f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21100 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
21110 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
21120 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21130 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21140 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21150 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
21160 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
21170 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
21180 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
21190 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
211a0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
211b0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
211c0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
211d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
211e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
211f0 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
21200 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
21210 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
21220 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21240 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
21250 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
21260 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
21270 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
21290 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
212a0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
212b0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
212c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
212d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
212e0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
212f0 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
21300 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
21310 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21320 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21330 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
21340 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
21350 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21360 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21370 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21380 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
21390 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
213a0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
213b0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
213c0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
213d0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
213e0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
213f0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
21400 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21410 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
21420 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
21430 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
21440 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
21450 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21460 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
21470 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
21480 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
21490 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
214a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
214b0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
214c0 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
214d0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
214e0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
214f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21500 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
21510 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
21520 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
21530 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21540 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21550 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
21560 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
21570 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
21580 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21590 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
215a0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
215b0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
215c0 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
215d0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
215e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
215f0 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
21600 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
21610 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21620 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
21630 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21640 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
21650 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
21660 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
21670 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21680 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21690 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
216a0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
216b0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
216c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
216d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
216e0 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
216f0 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
21700 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
21710 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
21720 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
21730 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
21740 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
21750 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
21760 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21770 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
21780 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
21790 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
217a0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
217b0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
217c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
217d0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
217e0 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
217f0 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
21800 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21810 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
21820 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
21830 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
21840 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21850 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21860 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
21870 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
21880 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
21890 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
218a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
218b0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
218c0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
218d0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
218e0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
218f0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
21900 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
21910 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
21920 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21930 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
21940 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
21950 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
21960 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
21970 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
21980 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
21990 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
219a0 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
219b0 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
219c0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
219d0 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
219e0 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
219f0 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
21a00 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
21a10 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
21a20 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
21a30 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
21a40 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
21a50 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
21a60 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
21a70 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
21a80 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
21a90 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
21aa0 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
21ab0 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
21ac0 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
21ad0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
21ae0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
21af0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
21b00 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
21b10 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
21b20 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
21b30 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
21b40 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
21b50 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
21b60 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  tep()]..** ^The 
21b70 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
21b80 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
21b90 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38  ked with a UTF-8
21ba0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
21bb0 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
21bc0 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73  nt text as the s
21bd0 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
21be0 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
21bf0 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c  .** ^(Additional
21c00 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
21c10 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74   callbacks might
21c20 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
21c30 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
21c40 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
21c50 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
21c60 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
21c70 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
21c80 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
21c90 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
21ca0 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a  e trigger.)^.**.
21cb0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
21cc0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
21cd0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
21ce0 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
21cf0 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
21d00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
21d10 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
21d20 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
21d30 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
21d40 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
21d50 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
21d60 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
21d70 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
21d80 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
21d90 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
21da0 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
21db0 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
21dc0 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
21dd0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
21de0 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
21df0 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
21e00 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
21e10 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
21e20 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
21e30 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
21e40 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
21e50 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
21e60 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
21e70 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
21e80 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
21e90 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
21ea0 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
21eb0 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
21ec0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
21ed0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
21ee0 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
21ef0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
21f00 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
21f10 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
21f20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
21f30 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
21f40 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ite..*/.SQLITE_A
21f50 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
21f60 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
21f70 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
21f80 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
21f90 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
21fa0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50  E_API SQLITE_EXP
21fb0 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
21fc0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
21fd0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
21fe0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
21ff0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
22000 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
22010 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
22020 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
22030 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
22040 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
22050 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
22060 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
22070 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
22080 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
22090 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
220a0 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
220b0 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
220c0 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
220d0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
220e0 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
220f0 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
22100 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
22110 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
22120 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
22130 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
22140 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
22150 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
22160 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
22170 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
22180 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
22190 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
221a0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
221b0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
221c0 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
221d0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
221e0 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
221f0 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75  eter N is the nu
22200 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
22210 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
22220 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
22230 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
22240 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
22250 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
22260 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
22270 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  X..**.** ^Only a
22280 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
22290 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
222a0 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
222b0 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
222c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
222d0 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
222e0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
222f0 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
22300 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
22310 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
22320 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
22330 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
22340 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
22350 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
22360 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
22370 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
22380 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
22390 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
223a0 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
223b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
223c0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
223d0 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
223e0 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
223f0 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
22400 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
22410 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
22420 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
22430 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
22440 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
22450 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
22460 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
22470 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
22480 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
22490 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
224a0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
224b0 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
224c0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
224d0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
224e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
224f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
22500 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
22510 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
22520 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
22530 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
22540 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
22550 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
22560 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  *.*/.SQLITE_API 
22570 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
22580 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
22590 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
225a0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
225b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
225c0 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
225d0 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
225e0 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
225f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
22600 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
22610 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
22620 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
22630 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
22640 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
22650 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
22660 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
22670 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
22680 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
22690 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
226a0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
226b0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
226c0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
226d0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
226e0 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
226f0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
22700 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
22710 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
22720 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
22730 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
22740 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
22750 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
22760 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
22770 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
22780 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
22790 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
227a0 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
227b0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
227c0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
227d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
227e0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
227f0 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
22800 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
22810 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
22820 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
22830 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
22840 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
22850 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
22860 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
22870 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
22880 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
22890 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
228a0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
228b0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
228c0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
228d0 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
228e0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
228f0 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
22900 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
22910 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
22920 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
22930 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
22940 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
22950 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
22960 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
22970 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71  e UTF-8 if.** sq
22980 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
22990 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
229a0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ) is called and.
229b0 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  ** UTF-16 in the
229c0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
229d0 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70  er if sqlite3_op
229e0 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a  en16() is used..
229f0 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
22a00 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
22a10 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
22a20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
22a30 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
22a40 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
22a50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
22a60 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
22a70 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
22a80 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
22a90 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
22aa0 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
22ab0 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
22ac0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
22ad0 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
22ae0 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
22af0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
22b00 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
22b10 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
22b20 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
22b30 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
22b40 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
22b50 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
22b60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
22b70 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
22b80 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
22b90 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
22ba0 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
22bb0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
22bc0 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
22bd0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
22be0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
22bf0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
22c00 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
22c10 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
22c20 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
22c30 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
22c40 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
22c50 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
22c60 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
22c70 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
22c80 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
22c90 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
22ca0 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
22cb0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
22cc0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
22cd0 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
22ce0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
22cf0 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
22d00 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
22d10 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
22d20 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
22d30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
22d40 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
22d50 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
22d60 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
22d70 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
22d80 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
22d90 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
22da0 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
22db0 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
22dc0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
22dd0 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
22de0 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
22df0 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
22e00 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
22e10 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
22e20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
22e30 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
22e40 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
22e50 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
22e60 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
22e70 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
22e80 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
22e90 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
22ea0 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
22eb0 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
22ec0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
22ed0 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
22ee0 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
22ef0 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
22f00 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
22f10 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
22f20 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
22f30 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
22f40 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
22f50 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
22f60 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22f70 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
22f80 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
22f90 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
22fa0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
22fb0 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
22fc0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
22fd0 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
22fe0 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
22ff0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
23000 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
23010 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
23020 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
23030 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
23040 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
23050 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
23060 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
23070 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
23080 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
23090 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
230a0 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
230b0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
230c0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
230d0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
230e0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
230f0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
23100 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
23110 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
23120 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
23130 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
23140 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
23150 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
23160 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
23170 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
23180 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
23190 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
231a0 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
231b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
231c0 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
231d0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
231e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
231f0 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
23200 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
23210 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
23220 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
23230 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
23240 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
23250 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
23260 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
23270 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
23280 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
23290 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
232a0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
232b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
232c0 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
232d0 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
232e0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
232f0 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
23300 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
23310 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
23320 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
23330 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
23340 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
23350 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
23360 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
23370 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
23380 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
23390 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
233a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
233b0 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
233c0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
233d0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
233e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
233f0 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
23400 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
23410 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
23420 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
23430 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
23440 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
23450 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
23460 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
23470 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
23480 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
23490 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
234a0 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
234b0 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
234c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
234d0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
234e0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
234f0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
23500 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
23510 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
23520 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
23530 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
23540 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
23550 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
23560 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
23570 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
23580 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
23590 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
235a0 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
235b0 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
235c0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
235d0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
235e0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
235f0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
23600 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
23610 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
23620 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
23630 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
23640 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
23650 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
23660 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
23670 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
23680 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
23690 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
236a0 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
236b0 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
236c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
236d0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
236e0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
236f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
23700 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
23710 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
23720 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
23730 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
23740 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
23750 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
23760 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
23770 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
23780 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
23790 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
237a0 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
237b0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
237c0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
237d0 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
237e0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
237f0 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
23800 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
23810 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
23820 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
23830 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
23840 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
23850 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
23860 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
23870 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
23880 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
23890 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
238a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
238b0 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
238c0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
238d0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
238e0 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
238f0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
23900 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
23910 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
23920 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
23930 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
23940 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
23950 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
23960 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
23970 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
23980 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
23990 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
239a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
239b0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
239c0 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
239d0 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
239e0 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
239f0 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
23a00 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
23a10 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
23a20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
23a30 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
23a40 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
23a50 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
23a60 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
23a70 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
23a80 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
23a90 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
23aa0 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
23ab0 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
23ac0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
23ad0 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
23ae0 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
23af0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
23b00 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
23b10 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
23b20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
23b30 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
23b40 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
23b50 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
23b60 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
23b70 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
23b80 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
23b90 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
23ba0 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
23bb0 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
23bc0 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
23bd0 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
23be0 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
23bf0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
23c00 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
23c10 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
23c20 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
23c30 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
23c40 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
23c50 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f  h. .** ^On windo
23c60 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
23c70 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
23c80 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
23c90 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
23ca0 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
23cb0 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f  C:")..**.** [[co
23cc0 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72  re URI query par
23cd0 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65  ameters]].** The
23ce0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
23cf0 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f   of a URI may co
23d00 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73  ntain parameters
23d10 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70   that are interp
23d20 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20  reted.** either 
23d30 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66  by SQLite itself
23d40 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c  , or by a [VFS |
23d50 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c   custom VFS impl
23d60 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  ementation]..** 
23d70 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
23d80 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  s the following 
23d90 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61  three query para
23da0 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
23db0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
23dc0 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
23dd0 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
23de0 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
23df0 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
23e00 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
23e10 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
23e20 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
23e30 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
23e40 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
23e50 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
23e60 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
23e70 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
23e80 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
23e90 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
23ea0 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
23eb0 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
23ec0 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
23ed0 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
23ee0 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
23ef0 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
23f00 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
23f10 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
23f20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
23f30 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
23f40 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
23f50 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
23f60 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
23f70 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
23f80 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
23f90 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
23fa0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
23fb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
23fc0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
23fd0 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
23fe0 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
23ff0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
24000 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
24010 20 22 72 77 22 20 6f 72 0a 2a 2a 20 20 20 20 20   "rw" or.**     
24020 22 72 77 63 22 2e 20 41 74 74 65 6d 70 74 69 6e  "rwc". Attemptin
24030 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61  g to set it to a
24040 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69  ny other value i
24050 73 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a  s an error)^. .*
24060 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
24070 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
24080 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
24090 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
240a0 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
240b0 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
240c0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
240d0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
240e0 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
240f0 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
24100 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
24110 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
24120 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f  v2(). ^If the mo
24130 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  de option is set
24140 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22   to .**     "rw"
24150 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
24160 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
24170 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75  r read-write (bu
24180 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a  t not create) .*
24190 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73  *     access, as
241a0 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   if SQLITE_OPEN_
241b0 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e  READWRITE (but n
241c0 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ot SQLITE_OPEN_C
241d0 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20  REATE) had .**  
241e0 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61     been set. ^Va
241f0 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75  lue "rwc" is equ
24200 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
24210 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20  ng both .**     
24220 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24230 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45  WRITE and SQLITE
24240 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 5e 49  _OPEN_CREATE. ^I
24250 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
24260 32 28 29 20 69 73 20 0a 2a 2a 20 20 20 20 20 75  2() is .**     u
24270 73 65 64 2c 20 69 74 20 69 73 20 61 6e 20 65 72  sed, it is an er
24280 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  ror to specify a
24290 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 6d   value for the m
242a0 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  ode parameter th
242b0 61 74 20 69 73 20 0a 2a 2a 20 20 20 20 20 6c 65  at is .**     le
242c0 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
242d0 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
242e0 65 64 20 62 79 20 74 68 65 20 66 6c 61 67 73 20  ed by the flags 
242f0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
24300 69 72 64 20 0a 2a 2a 20 20 20 20 20 70 61 72 61  ird .**     para
24310 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  meter..**.**   <
24320 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
24330 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
24340 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
24350 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
24360 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
24370 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
24380 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
24390 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
243a0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
243b0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
243c0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
243d0 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
243e0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
243f0 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
24400 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
24410 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
24420 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
24430 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
24440 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
24450 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
24460 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
24470 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
24480 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
24490 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
244a0 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
244b0 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
244c0 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
244d0 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
244e0 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
244f0 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72   any behaviour r
24500 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
24510 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
24520 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
24530 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
24540 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
24550 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  lag..** </ul>.**
24560 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
24570 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
24580 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
24590 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
245a0 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
245b0 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
245c0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
245d0 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
245e0 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
245f0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
24600 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
24610 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
24620 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
24630 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
24640 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
24650 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
24660 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
24670 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
24680 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
24690 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
246a0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
246b0 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
246c0 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
246d0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
246e0 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
246f0 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
24700 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
24710 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
24720 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
24730 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
24740 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
24750 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
24760 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
24770 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
24780 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
24790 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
247a0 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
247b0 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
247c0 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
247d0 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
247e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
247f0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
24800 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
24810 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
24820 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
24830 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
24840 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
24850 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
24860 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
24870 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
24880 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
24890 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
248a0 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
248b0 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
248c0 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
248d0 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
248e0 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
248f0 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
24900 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
24910 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
24920 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
24930 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
24940 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
24950 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
24960 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
24970 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
24980 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
24990 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
249a0 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
249b0 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
249c0 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
249d0 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
249e0 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
249f0 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
24a00 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
24a10 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
24a20 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
24a30 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
24a40 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
24a50 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
24a60 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
24a70 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
24a80 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
24a90 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
24aa0 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
24ab0 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
24ac0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
24ad0 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
24ae0 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
24af0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
24b00 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
24b10 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c  fs=unix-nolock <
24b20 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  td>.**          
24b30 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65  Open file "/home
24b40 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20  /fred/data.db". 
24b50 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20  Use the special 
24b60 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b  VFS "unix-nolock
24b70 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
24b80 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
24b90 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
24ba0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
24bb0 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
24bc0 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
24bd0 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
24be0 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
24bf0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
24c00 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
24c10 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
24c20 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
24c30 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
24c40 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
24c50 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
24c60 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
24c70 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
24c80 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
24c90 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
24ca0 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
24cb0 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
24cc0 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
24cd0 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
24ce0 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
24cf0 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
24d00 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
24d10 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
24d20 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
24d30 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
24d40 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
24d50 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
24d60 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
24d70 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
24d80 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
24d90 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
24da0 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
24db0 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
24dc0 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
24dd0 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
24de0 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
24df0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
24e00 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
24e10 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
24e20 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
24e30 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
24e40 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
24e50 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
24e60 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
24e70 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
24e80 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
24e90 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
24ea0 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
24eb0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
24ec0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
24ed0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
24ee0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
24ef0 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
24f00 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
24f10 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
24f20 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
24f30 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
24f40 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
24f50 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
24f60 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 53 51 4c 49 54  n_v2()..*/.SQLIT
24f70 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
24f80 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
24f90 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
24fa0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
24fb0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
24fc0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
24fd0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
24fe0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
24ff0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  ndle */.);.SQLIT
25000 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
25010 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
25020 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
25030 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
25040 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
25050 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
25060 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
25070 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
25080 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51   handle */.);.SQ
25090 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
250a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
250b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
250c0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
250d0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
250e0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
250f0 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
25100 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
25110 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
25120 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
25130 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
25140 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
25150 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
25160 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
25170 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
25180 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25190 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20  : Obtain Values 
251a0 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65  For URI Paramete
251b0 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  rs.**.** These a
251c0 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69  re utility routi
251d0 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  nes, useful to V
251e0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
251f0 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a  ns, that check.*
25200 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61  * to see if a da
25210 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20  tabase file was 
25220 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61  a URI that conta
25230 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20  ined a specific 
25240 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65  query .** parame
25250 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f  ter, and if so o
25260 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65  btains the value
25270 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70   of that query p
25280 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
25290 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61  If F is the data
252a0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f  base filename po
252b0 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74  inter passed int
252c0 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65  o the xOpen() me
252d0 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46  thod of .** a VF
252e0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
252f0 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20   when the flags 
25300 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
25310 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20  en() has one or 
25320 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
25330 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
25340 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
25350 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20  N_MAIN_DB] bits 
25360 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20  set and.** P is 
25370 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
25380 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c  query parameter,
25390 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
253a0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
253b0 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  ,P) returns the 
253c0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a  value of the P.*
253d0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
253e0 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55  t exists or a NU
253f0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20  LL pointer if P 
25400 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
25410 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70  as a .** query p
25420 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20  arameter on F.  
25430 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20  If P is a query 
25440 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a  parameter of F.*
25450 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69  * has no explici
25460 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71  t value, then sq
25470 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
25480 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
25490 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
254a0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
254b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
254c0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
254d0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61  F,P,B) routine a
254e0 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73  ssumes that P is
254f0 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61   a boolean.** pa
25500 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
25510 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20  rns true (1) or 
25520 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64  false (0) accord
25530 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ing to the value
25540 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73  .** of P.  The s
25550 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
25560 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
25570 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
25580 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c  1) if the.** val
25590 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61  ue of query para
255a0 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
255b0 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c  f "yes", "true",
255c0 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a   or "on" in any.
255d0 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68  ** case or if th
255e0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
255f0 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e  ith a non-zero n
25600 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20  umber.  The .** 
25610 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
25620 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
25630 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73  nes returns fals
25640 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c  e (0) if the val
25650 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70  ue of.** query p
25660 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
25670 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73  e of "no", "fals
25680 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20  e", or "off" in 
25690 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69  any case or.** i
256a0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
256b0 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69  ns with a numeri
256c0 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73  c zero.  If P is
256d0 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20   not a query.** 
256e0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f  parameter on F o
256f0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  r if the value o
25700 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20  f P is does not 
25710 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65  match any of the
25720 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20  .** above, then 
25730 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
25740 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
25750 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ns (B!=0)..**.**
25760 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
25770 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f  _int64(F,P,D) ro
25780 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74  utine converts t
25790 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e  he value of P in
257a0 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73  to a.** 64-bit s
257b0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
257c0 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69  d returns that i
257d0 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20  nteger, or D if 
257e0 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78  P does not.** ex
257f0 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c  ist.  If the val
25800 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74  ue of P is somet
25810 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
25820 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e  an integer, then
25830 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75  .** zero is retu
25840 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rned..** .** If 
25850 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  F is a NULL poin
25860 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ter, then sqlite
25870 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
25880 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  F,P) returns NUL
25890 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  L and.** sqlite3
258a0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
258b0 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20  ,B) returns B.  
258c0 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55  If F is not a NU
258d0 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a  LL pointer and.*
258e0 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  * is not a datab
258f0 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  ase file pathnam
25900 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53  e pointer that S
25910 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74  QLite passed int
25920 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56  o the xOpen.** V
25930 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  FS method, then 
25940 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
25950 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
25960 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
25970 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69  obably.** undesi
25980 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  rable..*/.SQLITE
25990 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
259a0 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72  *sqlite3_uri_par
259b0 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61  ameter(const cha
259c0 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f  r *zFilename, co
259d0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
259e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
259f0 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  t sqlite3_uri_bo
25a00 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72  olean(const char
25a10 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63   *zFile, const c
25a20 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74  har *zParam, int
25a30 20 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49   bDefault);.SQLI
25a40 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
25a50 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69  nt64 sqlite3_uri
25a60 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61  _int64(const cha
25a70 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  r*, const char*,
25a80 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
25a90 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
25aa0 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
25ab0 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a  nd Messages.**.*
25ac0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
25ad0 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61  rrcode() interfa
25ae0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
25af0 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
25b00 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
25b10 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
25b20 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72  ] for the most r
25b30 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c  ecent failed sql
25b40 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a  ite3_* API call.
25b50 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
25b60 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
25b70 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61  onnection]. If a
25b80 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20   prior API call 
25b90 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68  failed.** but th
25ba0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50  e most recent AP
25bb0 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64  I call succeeded
25bc0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
25bd0 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  ue from.** sqlit
25be0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20  e3_errcode() is 
25bf0 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  undefined.  ^The
25c00 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
25c10 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
25c20 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
25c30 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
25c40 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
25c50 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
25c60 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
25c70 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
25c80 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
25c90 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
25ca0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
25cb0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
25cc0 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
25cd0 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
25ce0 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
25cf0 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
25d00 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
25d10 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
25d20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
25d30 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
25d40 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
25d50 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
25d60 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
25d70 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
25d80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
25d90 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
25da0 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
25db0 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
25dc0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
25dd0 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
25de0 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
25df0 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
25e00 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
25e10 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
25e20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
25e30 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
25e40 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
25e50 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
25e60 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
25e70 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
25e80 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
25e90 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
25ea0 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
25eb0 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
25ec0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
25ed0 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
25ee0 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
25ef0 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
25f00 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
25f10 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
25f20 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
25f30 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
25f40 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
25f50 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
25f60 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
25f70 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
25f80 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
25f90 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
25fa0 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
25fb0 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
25fc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25fd0 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
25fe0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
25ff0 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
26000 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
26010 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
26020 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
26030 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
26040 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
26050 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
26060 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
26070 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
26080 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
26090 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
260a0 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
260b0 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
260c0 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
260d0 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
260e0 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
260f0 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
26100 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
26110 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
26120 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
26130 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
26140 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
26150 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
26160 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  e set..*/.SQLITE
26170 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
26180 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
26190 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50   *db);.SQLITE_AP
261a0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  I int sqlite3_ex
261b0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
261c0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c  qlite3 *db);.SQL
261d0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
261e0 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
261f0 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  sg(sqlite3*);.SQ
26200 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
26210 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
26220 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
26230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26240 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  : SQL Statement 
26250 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
26260 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
26270 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
26280 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
26290 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
262a0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
262b0 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
262c0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
262d0 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
262e0 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
262f0 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
26300 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
26310 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
26320 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
26330 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
26340 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
26350 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
26360 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
26370 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
26380 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
26390 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
263a0 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
263b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
263c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
263d0 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
263e0 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
263f0 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
26400 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
26410 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
26420 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
26430 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
26440 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
26450 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
26460 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
26470 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
26480 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
26490 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
264a0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
264b0 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
264c0 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
264d0 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
264e0 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
264f0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
26500 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
26510 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
26520 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
26530 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
26540 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
26550 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
26560 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
26570 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
26580 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
26590 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
265a0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
265b0 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
265c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
265d0 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a  n-time Limits.**
265e0 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
265f0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
26600 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
26610 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
26620 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
26630 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
26640 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
26650 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
26660 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
26670 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
26680 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
26690 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
266a0 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
266b0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
266c0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
266d0 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
266e0 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
266f0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
26700 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
26710 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
26720 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
26730 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
26740 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
26750 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
26760 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
26770 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
26780 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
26790 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
267a0 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
267b0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
267c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
267d0 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
267e0 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
267f0 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
26800 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
26810 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
26820 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
26830 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
26840 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
26850 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
26860 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
26870 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
26880 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
26890 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
268a0 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
268b0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
268c0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
268d0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
268e0 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
268f0 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
26900 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
26910 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
26920 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
26930 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
26940 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
26950 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
26960 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
26970 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
26980 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
26990 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
269a0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
269b0 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
269c0 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
269d0 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
269e0 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
269f0 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
26a00 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
26a10 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
26a20 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
26a30 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
26a40 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
26a50 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
26a60 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
26a70 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
26a80 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
26a90 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
26aa0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
26ab0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
26ac0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
26ad0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
26ae0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
26af0 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
26b00 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
26b10 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
26b20 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
26b30 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
26b40 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
26b50 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
26b60 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
26b70 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
26b80 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
26b90 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
26ba0 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
26bb0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
26bc0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
26bd0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
26be0 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
26bf0 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
26c00 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
26c10 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
26c20 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
26c30 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
26c40 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
26c50 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
26c60 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
26c70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
26c80 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
26c90 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
26ca0 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
26cb0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
26cc0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
26cd0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
26ce0 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
26cf0 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
26d00 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
26d10 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
26d20 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
26d30 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
26d40 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
26d50 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
26d60 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
26d70 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  leases..*/.SQLIT
26d80 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
26d90 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
26da0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
26db0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
26dc0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
26dd0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
26de0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
26df0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
26e00 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
26e10 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
26e20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
26e30 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
26e40 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
26e50 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
26e60 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
26e70 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
26e80 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
26e90 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
26ea0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
26eb0 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
26ec0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
26ed0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
26ee0 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
26ef0 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
26f00 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
26f10 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
26f20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26f30 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
26f40 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
26f50 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
26f60 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
26f70 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
26f80 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
26f90 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
26fa0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26fb0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
26fc0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
26fd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
26fe0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
26ff0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
27000 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
27010 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
27020 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
27030 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
27040 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
27050 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
27060 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
27070 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
27080 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
27090 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
270a0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
270b0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
270c0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
270d0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
270e0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
270f0 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
27100 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
27110 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
27120 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
27130 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
27140 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
27150 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
27160 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
27170 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
27180 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
27190 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
271a0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
271b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
271c0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
271d0 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
271e0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
271f0 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
27200 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
27210 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
27220 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
27230 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
27240 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
27250 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
27260 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
27270 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
27280 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
27290 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
272a0 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
272b0 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
272c0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
272d0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
272e0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
272f0 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
27300 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
27310 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
27320 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
27330 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
27340 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
27350 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
27360 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
27370 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
27380 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
27390 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
273a0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
273b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
273c0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
273d0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
273e0 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
273f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
27400 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
27410 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
27420 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
27430 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
27440 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
27450 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
27460 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
27470 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27480 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
27490 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
274a0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
274b0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
274c0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
274d0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
274e0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
274f0 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
27500 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
27510 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
27520 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
27530 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
27540 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
27550 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
27560 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
27570 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
27580 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
27590 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
275a0 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
275b0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
275c0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
275d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
275e0 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
275f0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
27600 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
27610 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
27620 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
27630 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
27640 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  ers.</dd>)^.** <
27650 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
27660 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
27670 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
27680 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
27690 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
276a0 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
276b0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
276c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
276d0 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
276e0 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
276f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
27700 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
27710 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
27720 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
27730 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
27740 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
27750 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27760 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
27770 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
27780 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27790 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
277a0 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
277b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
277c0 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
277d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
277e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
277f0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
27800 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
27810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27820 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
27830 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
27840 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
27850 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
27860 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
27870 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
27880 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
27890 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
278a0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
278b0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
278c0 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
278d0 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
278e0 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
278f0 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
27900 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
27910 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
27920 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
27930 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
27940 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
27950 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
27960 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
27970 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
27980 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
27990 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
279a0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
279b0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
279c0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
279d0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
279e0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
279f0 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
27a00 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
27a10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
27a20 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
27a30 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
27a40 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
27a50 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
27a60 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
27a70 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
27a80 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27a90 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
27aa0 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
27ab0 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
27ac0 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
27ad0 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
27ae0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27af0 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
27b00 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
27b10 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
27b20 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ent is less than
27b30 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
27b40 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
27b50 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
27b60 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
27b70 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
27b80 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
27b90 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  is the maximum.*
27ba0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74  * number of  byt
27bb0 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
27bc0 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20  l.  ^When nByte 
27bd0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
27be0 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
27bf0 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
27c00 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
27c10 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
27c20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
27c30 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
27c40 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
27c50 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
27c60 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
27c70 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
27c80 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
27c90 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
27ca0 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
27cb0 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
27cc0 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
27cd0 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
27ce0 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
27cf0 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
27d00 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
27d10 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
27d20 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
27d30 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
27d40 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
27d50 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20  erminator bytes 
27d60 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51  as this saves SQ
27d70 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67  Lite from having
27d80 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f   to.** make a co
27d90 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20  py of the input 
27da0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  string..**.** ^I
27db0 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
27dc0 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
27dd0 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
27de0 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
27df0 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
27e00 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
27e10 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
27e20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
27e30 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
27e40 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
27e50 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
27e60 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
27e70 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
27e80 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
27e90 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
27ea0 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
27eb0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
27ec0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
27ed0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27ee0 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
27ef0 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
27f00 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
27f10 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
27f20 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
27f30 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
27f40 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
27f50 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
27f60 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
27f70 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
27f80 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
27f90 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
27fa0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
27fb0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
27fc0 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
27fd0 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
27fe0 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
27ff0 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
28000 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
28010 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
28020 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
28030 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
28040 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
28050 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
28060 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
28070 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
28080 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
28090 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
280a0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
280b0 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
280c0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
280d0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
280e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
280f0 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
28100 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28110 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
28120 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
28130 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
28140 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
28150 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
28160 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
28170 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
28180 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
28190 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
281a0 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
281b0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
281c0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
281d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
281e0 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
281f0 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
28200 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
28210 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
28220 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
28230 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
28240 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
28250 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
28260 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
28270 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
28280 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
28290 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
282a0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
282b0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
282c0 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
282d0 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
282e0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
282f0 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
28300 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
28310 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
28320 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
28330 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
28340 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
28350 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
28360 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ain..** </li>.**
28370 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
28380 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
28390 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
283a0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
283b0 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
283c0 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
283d0 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
283e0 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
283f0 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
28400 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
28410 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
28420 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
28430 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
28440 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
28450 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
28460 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
28470 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
28480 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
28490 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
284a0 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
284b0 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
284c0 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
284d0 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
284e0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
284f0 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
28500 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
28510 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
28520 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
28530 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
28540 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
28550 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
28560 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
28570 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
28580 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
28590 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
285a0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
285b0 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
285c0 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
285d0 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
285e0 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
285f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
28600 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
28610 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
28620 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
28630 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
28640 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
28650 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
28660 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
28670 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
28680 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
28690 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
286a0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
286b0 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
286c0 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
286d0 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
286e0 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
286f0 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
28700 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
28710 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
28720 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
28730 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
28740 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
28750 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
28760 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
28770 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
28780 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
28790 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
287a0 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
287b0 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
287c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
287d0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
287e0 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69  .** the .** </li
287f0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51  >.** </ol>.*/.SQ
28800 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28810 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
28820 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
28830 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
28840 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
28850 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
28860 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
28870 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
28880 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
28890 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
288a0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
288b0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
288c0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
288d0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
288e0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
288f0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
28900 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
28910 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
28920 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
28930 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
28940 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
28950 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
28960 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
28970 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
28980 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
28990 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
289a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
289b0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
289c0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
289d0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
289e0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
289f0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
28a00 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
28a10 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
28a20 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
28a30 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
28a40 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
28a50 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
28a60 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
28a70 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
28a80 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
28a90 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c  f zSql */.);.SQL
28aa0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
28ab0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
28ac0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
28ad0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
28ae0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
28af0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
28b00 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
28b10 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
28b20 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
28b30 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
28b40 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
28b50 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
28b60 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
28b70 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
28b80 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
28b90 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
28ba0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
28bb0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
28bc0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
28bd0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
28be0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
28bf0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28c00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
28c10 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
28c20 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
28c30 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
28c40 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
28c50 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
28c60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
28c70 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
28c80 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
28c90 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
28ca0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
28cb0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
28cc0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
28cd0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
28ce0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
28cf0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
28d00 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
28d10 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
28d20 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
28d30 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
28d40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28d50 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
28d60 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a  atement SQL.**.*
28d70 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
28d80 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
28d90 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
28da0 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
28db0 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
28dc0 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
28dd0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
28de0 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
28df0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
28e00 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
28e10 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
28e20 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
28e30 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
28e40 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53  re16_v2()]..*/.S
28e50 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
28e60 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
28e70 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
28e80 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
28e90 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
28ea0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
28eb0 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68  tement Writes Th
28ec0 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a  e Database.**.**
28ed0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
28ee0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69  mt_readonly(X) i
28ef0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28f00 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
28f10 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20   if.** and only 
28f20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  if the [prepared
28f30 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61   statement] X ma
28f40 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68  kes no direct ch
28f50 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20  anges to.** the 
28f60 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
28f70 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
28f80 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61  .** Note that [a
28f90 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28fa0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
28fb0 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c  ] or.** [virtual
28fc0 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63   tables] might c
28fd0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
28fe0 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73  se indirectly as
28ff0 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20   a side effect. 
29000 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70   .** ^(For examp
29010 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63  le, if an applic
29020 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20  ation defines a 
29030 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29  function "eval()
29040 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73  " that .** calls
29050 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
29060 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c  ], then the foll
29070 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  owing SQL statem
29080 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61  ent would.** cha
29090 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
290a0 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69   file through si
290b0 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a  de-effects:.**.*
290c0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
290d0 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54  re>.**    SELECT
290e0 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52   eval('DELETE FR
290f0 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b  OM t1') FROM t2;
29100 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
29110 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75  kquote>.**.** Bu
29120 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53  t because the [S
29130 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
29140 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
29150 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
29160 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20  le.** directly, 
29170 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
29180 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74  donly() would st
29190 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e  ill return true.
291a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61  )^.**.** ^Transa
291b0 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74  ction control st
291c0 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73  atements such as
291d0 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49   [BEGIN], [COMMI
291e0 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a  T], [ROLLBACK],.
291f0 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20  ** [SAVEPOINT], 
29200 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61  and [RELEASE] ca
29210 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  use sqlite3_stmt
29220 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
29230 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73  eturn true,.** s
29240 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65  ince the stateme
29250 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64  nts themselves d
29260 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d  o not actually m
29270 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
29280 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72  se but.** rather
29290 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68   they control th
292a0 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e  e timing of when
292b0 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74   other statement
292c0 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a  s modify the .**
292d0 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65   database.  ^The
292e0 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44   [ATTACH] and [D
292f0 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74  ETACH] statement
29300 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20  s also cause.** 
29310 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
29320 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
29330 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68  n true since, wh
29340 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d  ile those statem
29350 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ents.** change t
29360 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
29370 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63   of a database c
29380 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20  onnection, they 
29390 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20  do not make .** 
293a0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63  changes to the c
293b0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
293c0 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20  tabase files on 
293d0 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  disk..*/.SQLITE_
293e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
293f0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
29400 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
29410 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
29420 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
29430 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
29440 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
29450 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Reset.**.** ^The
29460 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
29470 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
29480 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
29490 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
294a0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
294b0 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
294c0 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
294d0 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
294e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
294f0 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20  S)] but has not 
29500 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
29510 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74  n and/or has not
29520 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20   .** been reset 
29530 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
29540 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
29550 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
29560 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
29570 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
29580 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
29590 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
295a0 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
295b0 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
295c0 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
295d0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
295e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
295f0 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
29600 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
29610 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
29620 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
29630 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
29640 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
29650 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
29660 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
29670 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
29680 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
29690 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
296a0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
296b0 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
296c0 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
296d0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
296e0 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
296f0 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
29700 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
29710 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
29720 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
29730 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
29740 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
29750 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
29760 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53  ction open..*/.S
29770 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
29780 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
29790 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
297a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
297b0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
297c0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
297d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
297e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
297f0 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
29800 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29810 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
29820 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
29830 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
29840 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
29850 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
29860 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
29870 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
29880 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
29890 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
298a0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
298b0 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
298c0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
298d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
298e0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
298f0 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
29900 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
29910 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
29920 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
29930 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29940 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
29950 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
29960 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
29970 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
29980 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
29990 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
299a0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
299b0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
299c0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
299d0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
299e0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
299f0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
29a00 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
29a10 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
29a20 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
29a30 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
29a40 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
29a50 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
29a60 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
29a70 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
29a80 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
29a90 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
29aa0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
29ab0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
29ac0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
29ad0 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
29ae0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
29af0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
29b00 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29b10 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
29b20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
29b30 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
29b40 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29b50 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
29b60 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
29b70 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
29b80 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
29b90 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
29ba0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
29bb0 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
29bc0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
29bd0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
29be0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
29bf0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
29c00 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
29c10 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
29c20 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
29c30 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
29c40 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
29c50 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
29c60 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
29c70 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
29c80 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
29c90 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
29ca0 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
29cb0 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
29cc0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
29cd0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
29ce0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
29cf0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
29d00 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
29d10 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
29d20 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
29d30 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
29d40 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
29d50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
29d60 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
29d70 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
29d80 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
29d90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
29da0 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
29db0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
29dc0 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
29dd0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
29de0 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
29df0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
29e00 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
29e10 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
29e20 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
29e30 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
29e40 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
29e50 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
29e60 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
29e70 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
29e80 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29e90 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
29ea0 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
29eb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
29ec0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
29ed0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
29ee0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
29ef0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
29f00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
29f10 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
29f20 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
29f30 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
29f40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29f50 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
29f60 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
29f70 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
29f80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
29f90 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
29fa0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
29fb0 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
29fc0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
29fd0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
29fe0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
29ff0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2a000 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
2a010 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
2a020 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
2a030 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
2a040 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
2a050 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2a060 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2a070 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
2a080 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2a090 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
2a0a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
2a0b0 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
2a0c0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
2a0d0 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
2a0e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2a0f0 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
2a100 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
2a110 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2a120 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
2a130 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
2a140 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
2a150 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
2a160 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
2a170 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
2a180 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
2a190 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
2a1a0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2a1b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
2a1c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
2a1d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a1e0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
2a1f0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
2a200 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
2a210 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
2a220 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
2a230 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
2a240 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
2a250 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
2a260 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
2a270 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
2a280 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
2a290 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
2a2a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
2a2b0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
2a2c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2a2d0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
2a2e0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
2a2f0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
2a300 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
2a310 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
2a320 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
2a330 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
2a340 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
2a350 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
2a360 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
2a370 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
2a380 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
2a390 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
2a3a0 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
2a3b0 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
2a3c0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
2a3d0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
2a3e0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
2a3f0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
2a400 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
2a410 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
2a420 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
2a430 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
2a440 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
2a450 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
2a460 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
2a470 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
2a480 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2a490 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
2a4a0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
2a4b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2a4c0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
2a4d0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2a4e0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
2a4f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
2a500 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2a510 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
2a520 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
2a530 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
2a540 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
2a550 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2a560 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2a570 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
2a580 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
2a590 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
2a5a0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
2a5b0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2a5c0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
2a5d0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
2a5e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
2a5f0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
2a600 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
2a610 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
2a620 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
2a630 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
2a640 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
2a650 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
2a660 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
2a670 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
2a680 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
2a690 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
2a6a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a6b0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
2a6c0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
2a6d0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
2a6e0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
2a6f0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
2a700 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
2a710 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
2a720 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
2a730 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
2a740 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
2a750 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2a760 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
2a770 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
2a780 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
2a790 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2a7a0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
2a7b0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
2a7c0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ter..**.** ^(In 
2a7d0 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
2a7e0 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
2a7f0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
2a800 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
2a810 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2a820 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
2a830 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
2a840 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
2a850 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
2a860 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
2a870 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
2a880 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2a890 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
2a8a0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2a8b0 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
2a8c0 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
2a8d0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
2a8e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2a8f0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
2a900 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
2a910 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ator..** If a no
2a920 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
2a930 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
2a940 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
2a950 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
2a960 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2a970 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20  d_text16() then 
2a980 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
2a990 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
2a9a0 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
2a9b0 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
2a9c0 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
2a9d0 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
2a9e0 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
2a9f0 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
2aa00 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
2aa10 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
2aa20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
2aa30 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
2aa40 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
2aa50 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
2aa60 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
2aa70 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
2aa80 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
2aa90 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
2aaa0 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
2aab0 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
2aac0 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
2aad0 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
2aae0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2aaf0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2ab00 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2ab10 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
2ab20 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
2ab30 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
2ab40 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
2ab50 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
2ab60 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
2ab70 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
2ab80 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
2ab90 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
2aba0 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65  ith it.  ^The de
2abb0 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
2abc0 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65  ed.** to dispose
2abd0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
2abe0 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74  string even if t
2abf0 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  he call to sqlit
2ac00 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a  e3_bind_blob(),.
2ac10 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
2ac20 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74  text(), or sqlit
2ac30 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
2ac40 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66   fails.  .** ^If
2ac50 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2ac60 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
2ac70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
2ac80 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
2ac90 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
2aca0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
2acb0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
2acc0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
2acd0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
2ace0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
2acf0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
2ad00 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2ad10 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
2ad20 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
2ad30 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
2ad40 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
2ad50 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
2ad60 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
2ad70 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
2ad80 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2ad90 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
2ada0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
2adb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2adc0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
2add0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
2ade0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
2adf0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
2ae00 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
2ae10 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
2ae20 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
2ae30 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
2ae40 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
2ae50 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
2ae60 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
2ae70 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
2ae80 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
2ae90 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
2aea0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
2aeb0 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
2aec0 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
2aed0 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
2aee0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
2aef0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
2af00 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
2af10 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
2af20 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
2af30 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
2af40 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
2af50 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49  h BLOB..**.** ^I
2af60 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
2af70 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2af80 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2af90 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
2afa0 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
2afb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2afc0 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
2afd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2afe0 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
2aff0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2b000 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
2b010 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
2b020 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
2b030 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
2b040 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
2b050 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
2b060 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
2b070 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
2b080 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
2b090 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
2b0a0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2b0b0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2b0c0 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
2b0d0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2b0e0 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
2b0f0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
2b100 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
2b110 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
2b120 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
2b130 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
2b140 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2b150 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
2b160 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
2b170 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
2b180 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
2b190 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
2b1a0 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
2b1b0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
2b1c0 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
2b1d0 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
2b1e0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
2b1f0 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
2b200 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
2b210 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
2b220 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
2b230 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
2b240 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
2b250 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2b260 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b270 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
2b280 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2b290 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2b2a0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
2b2b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2b2c0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
2b2d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2b2e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
2b2f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b300 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2b310 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
2b320 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
2b330 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2b340 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
2b350 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
2b360 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50  uble);.SQLITE_AP
2b370 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2b380 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
2b390 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
2b3a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2b3b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2b3c0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2b3d0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
2b3e0 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt64);.SQLITE_AP
2b3f0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2b400 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
2b410 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  stmt*, int);.SQL
2b420 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2b430 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
2b440 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b450 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
2b460 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
2b470 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
2b480 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2b490 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
2b4a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2b4b0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2b4c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2b4d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2b4e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2b4f0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2b500 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
2b510 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2b520 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2b530 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2b540 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2b550 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
2b560 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b570 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
2b580 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e  rameters.**.** ^
2b590 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
2b5a0 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
2b5b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
2b5c0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
2b5d0 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
2b5e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
2b5f0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
2b600 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
2b610 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
2b620 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
2b630 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
2b640 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
2b650 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2b660 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
2b670 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2b680 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
2b690 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2b6a0 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
2b6b0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
2b6c0 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
2b6d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
2b6e0 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
2b6f0 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
2b700 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
2b710 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
2b720 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
2b730 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
2b740 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2b750 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
2b760 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
2b770 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
2b780 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
2b790 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
2b7a0 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
2b7b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2b7c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2b7d0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2b7e0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2b7f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2b800 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
2b810 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2b820 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2b830 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2b840 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2b850 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2b860 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2b870 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b880 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
2b890 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a   Parameter.**.**
2b8a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2b8b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2b8c0 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
2b8d0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2b8e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
2b8f0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
2b900 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
2b910 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2b920 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
2b930 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
2b940 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
2b950 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
2b960 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
2b970 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
2b980 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
2b990 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
2b9a0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
2b9b0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2b9c0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2b9d0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
2b9e0 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
2b9f0 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
2ba00 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
2ba10 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
2ba20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
2ba30 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
2ba40 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
2ba50 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
2ba60 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
2ba70 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
2ba80 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
2ba90 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
2baa0 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
2bab0 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
2bac0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2bad0 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
2bae0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
2baf0 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
2bb00 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
2bb10 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
2bb20 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
2bb30 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
2bb40 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
2bb50 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
2bb60 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
2bb70 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
2bb80 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
2bb90 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
2bba0 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
2bbb0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
2bbc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2bbd0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2bbe0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2bbf0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
2bc00 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2bc10 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2bc20 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2bc30 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2bc40 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
2bc50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2bc60 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2bc70 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
2bc80 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2bc90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2bca0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
2bcb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
2bcc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bcd0 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
2bce0 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
2bcf0 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e  ven Name.**.** ^
2bd00 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
2bd10 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
2bd20 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
2bd30 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
2bd40 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
2bd50 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
2bd60 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
2bd70 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
2bd80 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
2bd90 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2bda0 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
2bdb0 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
2bdc0 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
2bdd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
2bde0 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
2bdf0 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
2be00 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
2be10 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
2be20 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
2be30 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
2be40 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
2be50 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
2be60 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2be70 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2be80 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2be90 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2bea0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2beb0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2bec0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2bed0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2bee0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2bef0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2bf00 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2bf10 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2bf20 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
2bf30 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
2bf40 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
2bf50 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
2bf60 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
2bf70 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2bf80 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  nt.**.** ^Contra
2bf90 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
2bfa0 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
2bfb0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
2bfc0 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
2bfd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2bfe0 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
2bff0 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
2c000 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2c010 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
2c020 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
2c030 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
2c040 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c   to NULL..*/.SQL
2c050 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2c060 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2c070 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2c080 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c090 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
2c0a0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
2c0b0 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  t Set.**.** ^Ret
2c0c0 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
2c0d0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2c0e0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
2c0f0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
2c100 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c110 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
2c120 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2c130 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
2c140 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
2c150 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
2c160 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
2c170 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
2c180 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2c190 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
2c1a0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49  count()].*/.SQLI
2c1b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2c1c0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2c1d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2c1e0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2c1f0 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
2c200 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
2c210 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  Set.**.** ^These
2c220 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2c230 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
2c240 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
2c250 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
2c260 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2c270 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
2c280 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
2c290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2c2a0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
2c2b0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2c2c0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2c2d0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
2c2e0 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
2c2f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2c300 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
2c310 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2c320 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
2c330 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2c340 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2c350 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
2c360 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2c370 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
2c380 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
2c390 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
2c3a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2c3b0 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
2c3c0 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
2c3d0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
2c3e0 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
2c3f0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2c400 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
2c410 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
2c420 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
2c430 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2c440 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
2c450 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2c460 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2c470 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2c480 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2c490 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2c4a0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2c4b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c4c0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2c4d0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2c4e0 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
2c4f0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2c500 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
2c510 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2c520 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
2c530 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
2c540 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
2c550 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
2c560 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
2c570 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
2c580 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
2c590 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
2c5a0 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
2c5b0 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
2c5c0 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
2c5d0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2c5e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
2c5f0 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
2c600 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
2c610 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
2c620 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
2c630 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
2c640 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
2c650 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
2c660 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
2c670 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
2c680 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
2c690 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
2c6a0 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
2c6b0 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
2c6c0 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
2c6d0 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  next..*/.SQLITE_
2c6e0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2c6f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2c700 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2c710 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54  *, int N);.SQLIT
2c720 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2c730 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2c740 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2c750 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
2c760 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c770 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
2c780 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
2c790 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2c7a0 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
2c7b0 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
2c7c0 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
2c7d0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
2c7e0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
2c7f0 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
2c800 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
2c810 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
2c820 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
2c830 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
2c840 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
2c850 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
2c860 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
2c870 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
2c880 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
2c890 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2c8a0 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
2c8b0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
2c8c0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
2c8d0 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
2c8e0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2c8f0 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
2c900 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
2c910 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
2c920 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
2c930 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
2c940 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2c950 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
2c960 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c970 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
2c980 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
2c990 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2c9a0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2c9b0 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2c9c0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2c9d0 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2c9e0 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2c9f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2ca00 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2ca10 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2ca20 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
2ca30 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
2ca40 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
2ca50 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
2ca60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2ca70 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
2ca80 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
2ca90 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
2caa0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2cab0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
2cac0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
2cad0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2cae0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
2caf0 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
2cb00 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2cb10 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
2cb20 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2cb30 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
2cb40 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
2cb50 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2cb60 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
2cb70 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
2cb80 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
2cb90 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
2cba0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
2cbb0 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
2cbc0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2cbd0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
2cbe0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
2cbf0 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
2cc00 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
2cc10 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
2cc20 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
2cc30 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
2cc40 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
2cc50 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2cc60 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
2cc70 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
2cc80 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
2cc90 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
2cca0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
2ccb0 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
2ccc0 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
2ccd0 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
2cce0 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
2ccf0 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
2cd00 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
2cd10 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
2cd20 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
2cd30 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
2cd40 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
2cd50 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
2cd60 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
2cd70 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
2cd80 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
2cd90 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
2cda0 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
2cdb0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
2cdc0 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
2cdd0 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
2cde0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
2cdf0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
2ce00 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
2ce10 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2ce20 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
2ce30 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
2ce40 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
2ce50 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2ce60 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2ce70 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
2ce80 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
2ce90 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
2cea0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
2ceb0 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
2cec0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2ced0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
2cee0 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
2cef0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
2cf00 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
2cf10 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
2cf20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2cf30 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
2cf40 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
2cf50 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
2cf60 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
2cf70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cf80 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
2cf90 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
2cfa0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2cfb0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2cfc0 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ined..*/.SQLITE_
2cfd0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2cfe0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2cff0 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
2d000 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2d010 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2d020 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2d030 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2d040 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2d050 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2d060 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2d070 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2d080 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2d090 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2d0a0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2d0b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2d0c0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
2d0d0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2d0e0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2d0f0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2d100 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2d110 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
2d120 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2d130 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2d140 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2d150 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
2d160 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2d170 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2d180 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
2d190 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
2d1a0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
2d1b0 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
2d1c0 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
2d1d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2d1e0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
2d1f0 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
2d200 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
2d210 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
2d220 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
2d230 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
2d240 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
2d250 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
2d260 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
2d270 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2d280 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
2d290 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
2d2a0 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
2d2b0 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
2d2c0 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
2d2d0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2d2e0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
2d2f0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
2d300 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
2d310 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2d320 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
2d330 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2d340 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
2d350 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
2d360 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2d370 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
2d380 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
2d390 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
2d3a0 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
2d3b0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
2d3c0 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
2d3d0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
2d3e0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
2d3f0 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
2d400 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
2d410 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
2d420 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
2d430 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
2d440 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
2d450 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
2d460 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
2d470 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
2d480 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
2d490 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
2d4a0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
2d4b0 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
2d4c0 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
2d4d0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
2d4e0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
2d4f0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
2d500 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
2d510 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
2d520 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
2d530 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
2d540 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
2d550 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
2d560 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
2d570 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
2d580 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
2d590 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
2d5a0 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
2d5b0 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
2d5c0 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
2d5d0 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
2d5e0 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
2d5f0 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
2d600 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2d610 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2d620 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2d630 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2d640 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2d650 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2d660 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2d670 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
2d680 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2d690 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
2d6a0 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
2d6b0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66  atement.**.** Af
2d6c0 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
2d6d0 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
2d6e0 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
2d6f0 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
2d700 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2d710 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2d720 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2d730 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
2d740 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2d750 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
2d760 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
2d770 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
2d780 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2d790 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
2d7a0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
2d7b0 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
2d7c0 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
2d7d0 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
2d7e0 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
2d7f0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
2d800 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
2d810 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
2d820 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
2d830 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
2d840 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
2d850 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
2d860 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2d870 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2d880 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2d890 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
2d8a0 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
2d8b0 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
2d8c0 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2d8d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2d8e0 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
2d8f0 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
2d900 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2d910 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
2d920 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2d930 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
2d940 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
2d950 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
2d960 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
2d970 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
2d980 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
2d990 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
2d9a0 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
2d9b0 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
2d9c0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
2d9d0 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
2d9e0 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
2d9f0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
2da00 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
2da10 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
2da20 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
2da30 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
2da40 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
2da50 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
2da60 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
2da70 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
2da80 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
2da90 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
2daa0 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
2dab0 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
2dac0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
2dad0 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
2dae0 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
2daf0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2db00 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
2db10 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
2db20 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
2db30 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
2db40 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
2db50 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
2db60 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
2db70 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
2db80 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
2db90 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
2dba0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2dbb0 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
2dbc0 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
2dbd0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
2dbe0 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
2dbf0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
2dc00 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
2dc10 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
2dc20 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
2dc30 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
2dc40 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
2dc50 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2dc60 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2dc70 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
2dc80 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
2dc90 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
2dca0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2dcb0 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
2dcc0 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
2dcd0 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
2dce0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2dcf0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2dd00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
2dd10 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
2dd20 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
2dd30 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
2dd40 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2dd50 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
2dd60 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
2dd70 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
2dd80 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
2dd90 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
2dda0 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
2ddb0 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
2ddc0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2ddd0 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
2dde0 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
2ddf0 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
2de00 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
2de10 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2de20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
2de30 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
2de40 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
2de50 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
2de60 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
2de70 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
2de80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2de90 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2dea0 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
2deb0 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
2dec0 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
2ded0 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
2dee0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
2def0 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
2df00 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2df10 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
2df20 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
2df30 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
2df40 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2df50 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
2df60 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
2df70 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
2df80 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
2df90 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
2dfa0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2dfb0 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
2dfc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2dfd0 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
2dfe0 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
2dff0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
2e000 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
2e010 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2e020 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
2e030 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
2e040 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
2e050 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
2e060 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
2e070 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
2e080 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
2e090 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
2e0a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e0b0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
2e0c0 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
2e0d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e0e0 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
2e0f0 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
2e100 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
2e110 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2e120 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
2e130 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
2e140 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
2e150 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
2e160 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2e170 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
2e180 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
2e190 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
2e1a0 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
2e1b0 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
2e1c0 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
2e1d0 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
2e1e0 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
2e1f0 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
2e200 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2e210 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
2e220 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
2e230 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
2e240 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
2e250 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2e260 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
2e270 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
2e280 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
2e290 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2e2a0 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
2e2b0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2e2c0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
2e2d0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2e2e0 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
2e2f0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
2e300 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
2e310 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
2e320 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
2e330 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
2e340 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
2e350 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
2e360 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2e370 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
2e380 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
2e390 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
2e3a0 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
2e3b0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2e3c0 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
2e3d0 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
2e3e0 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
2e3f0 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
2e400 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
2e410 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
2e420 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
2e430 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
2e440 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
2e450 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
2e460 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
2e470 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2e480 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
2e490 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
2e4a0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
2e4b0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
2e4c0 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
2e4d0 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
2e4e0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2e4f0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2e500 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
2e510 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
2e520 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
2e530 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
2e540 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
2e550 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
2e560 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
2e570 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2e580 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
2e590 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2e5a0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2e5b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
2e5c0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
2e5d0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
2e5e0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2e5f0 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
2e600 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
2e610 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
2e620 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
2e630 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
2e640 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
2e650 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
2e660 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2e670 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
2e680 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
2e690 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
2e6a0 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
2e6b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e6c0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2e6d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2e6e0 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
2e6f0 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
2e700 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2e710 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2e720 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
2e730 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
2e740 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2e750 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
2e760 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
2e770 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
2e780 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
2e790 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
2e7a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2e7b0 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c  ommended..*/.SQL
2e7c0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2e7d0 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
2e7e0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2e7f0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2e800 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
2e810 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a   result set.**.*
2e820 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2e830 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74  ata_count(P) int
2e840 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2e850 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2e860 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63  umns in the.** c
2e870 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2e880 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2e890 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e8a0 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70  ent] P..** ^If p
2e8b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e8c0 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  t P does not hav
2e8d0 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20  e results ready 
2e8e0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69  to return.** (vi
2e8f0 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b  a calls to the [
2e900 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2e910 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt | sqlite3_col
2e920 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69  umn_*()] of.** i
2e930 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20  nterfaces) then 
2e940 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2e950 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e  nt(P) returns 0.
2e960 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e970 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2e980 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75  outine also retu
2e990 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20  rns 0 if P is a 
2e9a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2e9b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2e9c0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
2e9d0 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
2e9e0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
2e9f0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2ea00 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2ea10 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ned [SQLITE_DONE
2ea20 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
2ea30 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a  _data_count(P).*
2ea40 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f  * will return no
2ea50 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f  n-zero if previo
2ea60 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  us call to [sqli
2ea70 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2ea80 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2ea90 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e  _ROW], except in
2eaa0 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65   the case of the
2eab0 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65   [PRAGMA increme
2eac0 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20  ntal_vacuum].** 
2ead0 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20  where it always 
2eae0 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e  returns zero sin
2eaf0 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20  ce each step of 
2eb00 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a  that multi-step.
2eb10 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e  ** pragma return
2eb20 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64  s 0 columns of d
2eb30 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ata..**.** See a
2eb40 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
2eb50 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
2eb60 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2eb70 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2eb80 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2eb90 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2eba0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
2ebb0 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
2ebc0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
2ebd0 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
2ebe0 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
2ebf0 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
2ec00 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
2ec10 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
2ec20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2ec30 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2ec40 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
2ec50 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
2ec60 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2ec70 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
2ec80 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
2ec90 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
2eca0 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
2ecb0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
2ecc0 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
2ecd0 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
2ece0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
2ecf0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
2ed00 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
2ed10 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
2ed20 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
2ed30 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
2ed40 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
2ed50 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
2ed60 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
2ed70 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
2ed80 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
2ed90 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
2eda0 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
2edb0 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
2edc0 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
2edd0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
2ede0 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
2edf0 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
2ee00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
2ee10 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
2ee20 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
2ee30 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
2ee40 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
2ee50 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
2ee60 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2ee70 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
2ee80 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
2ee90 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
2eea0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2eeb0 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
2eec0 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
2eed0 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
2eee0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
2eef0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2ef00 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
2ef10 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72  esult set" inter
2ef20 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  face..**.** ^The
2ef30 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2ef40 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2ef50 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
2ef60 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
2ef70 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
2ef80 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
2ef90 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
2efa0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2efb0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
2efc0 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
2efd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2efe0 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
2eff0 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
2f000 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
2f010 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
2f020 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
2f030 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
2f040 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
2f050 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
2f060 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2f070 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2f080 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
2f090 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
2f0a0 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
2f0b0 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
2f0c0 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
2f0d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
2f0e0 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
2f0f0 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
2f100 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2f110 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
2f120 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
2f130 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2f140 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
2f150 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
2f160 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2f170 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
2f180 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
2f190 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
2f1a0 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
2f1b0 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
2f1c0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2f1d0 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
2f1e0 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
2f1f0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
2f200 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2f210 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2f220 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2f230 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
2f240 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
2f250 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2f260 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
2f270 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
2f280 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
2f290 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
2f2a0 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
2f2b0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2f2c0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
2f2d0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2f2e0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2f2f0 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
2f300 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2f310 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
2f320 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
2f330 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2f340 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
2f350 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2f360 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
2f370 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2f380 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2f390 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2f3a0 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
2f3b0 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
2f3c0 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
2f3d0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2f3e0 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
2f3f0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
2f400 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2f410 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2f420 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2f430 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
2f440 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
2f450 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
2f460 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
2f470 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
2f480 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
2f490 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
2f4a0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
2f4b0 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
2f4c0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2f4d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
2f4e0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
2f4f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
2f500 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
2f510 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
2f520 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
2f530 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2f540 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
2f550 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
2f560 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
2f570 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
2f580 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
2f590 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
2f5a0 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
2f5b0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
2f5c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2f5d0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
2f5e0 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
2f5f0 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
2f600 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
2f610 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
2f620 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
2f630 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
2f640 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
2f650 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
2f660 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2f670 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
2f680 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2f690 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f6a0 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
2f6b0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2f6c0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2f6d0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2f6e0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2f6f0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2f700 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
2f710 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2f720 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
2f730 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2f740 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
2f750 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2f760 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2f770 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2f780 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2f790 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2f7a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2f7b0 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2f7c0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2f7d0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2f7e0 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
2f7f0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2f800 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2f810 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2f820 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2f830 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2f840 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2f850 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
2f860 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
2f870 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2f880 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2f890 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
2f8a0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2f8b0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
2f8c0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2f8d0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2f8e0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2f8f0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2f900 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2f910 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
2f920 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
2f930 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2f940 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2f950 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
2f960 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
2f970 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2f980 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2f990 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2f9a0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2f9b0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2f9c0 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
2f9d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2f9e0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2f9f0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2fa00 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2fa10 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2fa20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2fa30 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
2fa40 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2fa50 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
2fa60 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2fa70 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
2fa80 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
2fa90 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
2faa0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
2fab0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2fac0 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
2fad0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2fae0 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
2faf0 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
2fb00 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
2fb10 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
2fb20 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
2fb30 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
2fb40 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2fb50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fb60 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
2fb70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2fb80 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
2fb90 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
2fba0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
2fbb0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
2fbc0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
2fbd0 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
2fbe0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2fbf0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2fc00 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2fc10 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
2fc20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
2fc30 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
2fc40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
2fc50 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
2fc60 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
2fc70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2fc80 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
2fc90 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
2fca0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
2fcb0 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
2fcc0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
2fcd0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2fce0 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
2fcf0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2fd00 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
2fd10 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
2fd20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2fd30 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
2fd40 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
2fd50 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2fd60 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2fd70 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2fd80 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
2fd90 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2fda0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
2fdb0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2fdc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2fdd0 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
2fde0 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
2fdf0 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
2fe00 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
2fe10 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
2fe20 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
2fe30 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2fe40 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
2fe50 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
2fe60 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
2fe70 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2fe80 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
2fe90 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
2fea0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
2feb0 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
2fec0 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
2fed0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
2fee0 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
2fef0 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
2ff00 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
2ff10 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
2ff20 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
2ff30 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
2ff40 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
2ff50 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
2ff60 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
2ff70 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
2ff80 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
2ff90 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
2ffa0 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
2ffb0 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
2ffc0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
2ffd0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
2ffe0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
2fff0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
30000 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
30010 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
30020 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
30030 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
30040 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
30050 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
30060 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
30070 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
30080 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
30090 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
300a0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
300b0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
300c0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
300d0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
300e0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
300f0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
30100 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
30110 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
30120 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
30130 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
30140 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
30150 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
30160 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
30170 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
30180 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
30190 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
301a0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
301b0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
301c0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
301d0 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
301e0 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
301f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
30200 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
30210 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
30220 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
30230 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
30240 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
30250 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
30260 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
30270 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
30280 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
30290 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
302a0 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
302b0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
302c0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
302d0 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
302e0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
302f0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
30300 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
30310 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
30320 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
30330 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
30340 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
30350 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
30360 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
30370 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
30380 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
30390 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
303a0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
303b0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
303c0 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
303d0 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
303e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
303f0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
30400 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
30410 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
30420 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
30430 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
30440 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
30450 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
30460 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
30470 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
30480 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
30490 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
304a0 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
304b0 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
304c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
304d0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
304e0 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
304f0 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
30500 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
30510 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
30520 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
30530 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
30540 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
30550 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
30560 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
30570 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
30580 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
30590 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
305a0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
305b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
305c0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
305d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
305e0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
305f0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
30600 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
30610 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
30620 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
30630 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
30640 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
30650 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
30660 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
30670 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
30680 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
30690 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
306a0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
306b0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
306c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
306d0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
306e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
306f0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
30700 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
30710 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
30720 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
30730 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
30740 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
30750 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
30760 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
30770 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
30780 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
30790 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
307a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
307b0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
307c0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
307d0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
307e0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
307f0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
30800 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
30810 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
30820 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
30830 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
30840 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
30850 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
30860 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
30870 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
30880 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
30890 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
308a0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
308b0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
308c0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
308d0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
308e0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
308f0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
30900 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
30910 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
30920 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
30930 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
30940 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
30950 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
30960 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
30970 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
30980 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
30990 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
309a0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
309b0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
309c0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
309d0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
309e0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
309f0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
30a00 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
30a10 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
30a20 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
30a30 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
30a40 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
30a50 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
30a60 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
30a70 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
30a80 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
30a90 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
30aa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30ab0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
30ac0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
30ad0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
30ae0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
30af0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
30b00 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
30b10 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
30b20 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
30b30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
30b40 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
30b50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30b60 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
30b70 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
30b80 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
30b90 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
30ba0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30bb0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
30bc0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
30bd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30be0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
30bf0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
30c00 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
30c10 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
30c20 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
30c30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
30c40 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
30c50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
30c60 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
30c70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
30c80 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
30c90 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
30ca0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
30cb0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
30cc0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
30cd0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
30ce0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
30cf0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
30d00 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
30d10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30d20 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
30d30 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
30d40 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
30d50 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
30d60 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
30d70 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
30d80 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
30d90 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
30da0 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
30db0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
30dc0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
30dd0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
30de0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
30df0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
30e00 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
30e10 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
30e20 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
30e30 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
30e40 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
30e50 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
30e60 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
30e70 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
30e80 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
30e90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
30ea0 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
30eb0 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
30ec0 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
30ed0 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
30ee0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
30ef0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
30f00 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
30f10 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
30f20 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
30f30 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
30f40 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
30f50 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
30f60 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
30f70 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
30f80 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
30f90 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
30fa0 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
30fb0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
30fc0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
30fd0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
30fe0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
30ff0 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
31000 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
31010 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
31020 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31030 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
31040 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
31050 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
31060 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31070 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
31080 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
31090 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
310a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
310b0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
310c0 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  API double sqlit
310d0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
310e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
310f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
31100 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
31110 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
31120 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
31130 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
31140 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
31150 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
31160 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
31170 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
31180 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
31190 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
311a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
311b0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
311c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
311d0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
311e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
311f0 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
31200 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
31210 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
31220 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
31230 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
31240 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
31250 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
31260 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
31270 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
31280 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31290 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
312a0 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
312b0 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
312c0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
312d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
312e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
312f0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
31300 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
31310 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31320 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
31330 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
31340 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
31350 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
31360 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
31370 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
31380 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
31390 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
313a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
313b0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
313c0 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
313d0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
313e0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
313f0 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
31400 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
31410 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
31420 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
31430 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
31440 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
31450 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
31460 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31470 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
31480 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
31490 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
314a0 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
314b0 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
314c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
314d0 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
314e0 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
314f0 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
31500 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
31510 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
31520 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
31530 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
31540 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
31550 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
31560 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
31570 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
31580 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
31590 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
315a0 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
315b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
315c0 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
315d0 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
315e0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
315f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
31600 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
31610 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
31620 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
31630 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
31640 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
31650 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
31660 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
31670 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
31680 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
31690 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
316a0 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
316b0 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
316c0 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
316d0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
316e0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
316f0 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
31700 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
31710 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
31720 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
31730 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
31740 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
31750 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
31760 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
31770 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
31780 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
31790 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
317a0 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
317b0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
317c0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
317d0 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
317e0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
317f0 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
31800 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
31810 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
31820 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
31830 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
31840 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
31850 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65  ^Any SQL stateme
31860 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
31870 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
31880 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
31890 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
318a0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
318b0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
318c0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
318d0 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
318e0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
318f0 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
31900 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
31910 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
31920 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
31930 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
31940 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
31950 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61  atement] S.** ba
31960 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
31970 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
31980 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  am..**.** ^If th
31990 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
319a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
319b0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
319c0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
319d0 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
319e0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
319f0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
31a00 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69  ,.** or if [sqli
31a10 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
31a20 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
31a30 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
31a40 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** then [sqlite3
31a50 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
31a60 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
31a70 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
31a80 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
31a90 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
31aa0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
31ab0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31ac0 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
31ad0 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
31ae0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
31af0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
31b00 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
31b10 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
31b20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
31b30 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
31b40 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
31b50 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
31b60 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
31b70 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
31b80 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70  gs] on the [prep
31b90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31ba0 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  S..*/.SQLITE_API
31bb0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73   int sqlite3_res
31bc0 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
31bd0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
31be0 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
31bf0 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
31c00 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45   Functions.** KE
31c10 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
31c20 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
31c30 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
31c40 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
31c50 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
31c60 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
31c70 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
31c80 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
31c90 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions}.**.** ^The
31ca0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  se functions (co
31cb0 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
31cc0 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
31cd0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
31ce0 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
31cf0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
31d00 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
31d10 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
31d20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
31d30 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
31d40 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
31d50 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
31d60 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62  ly differences b
31d70 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20  etween.** these 
31d80 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65  routines are the
31d90 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65   text encoding e
31da0 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74  xpected for.** t
31db0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
31dc0 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66  ter (the name of
31dd0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
31de0 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  ing created).** 
31df0 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65  and the presence
31e00 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61   or absence of a
31e10 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
31e20 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20  back for.** the 
31e30 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
31e40 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
31e50 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
31e60 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
31e70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31e80 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
31e90 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
31ea0 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
31eb0 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ^If an applicati
31ec0 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  on uses more tha
31ed0 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
31ee0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65  * connection the
31ef0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
31f00 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
31f10 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
31f20 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74  d.** to each dat
31f30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31f40 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
31f50 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  ** ^The second p
31f60 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
31f70 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
31f80 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
31f90 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
31fa0 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
31fb0 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
31fc0 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
31fd0 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54  55 bytes in a UT
31fe0 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  F-8.** represent
31ff0 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65  ation, exclusive
32000 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   of the zero-ter
32010 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20  minator.  ^Note 
32020 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  that the name.**
32030 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
32040 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c   in UTF-8 bytes,
32050 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20   not characters 
32060 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73  nor UTF-16 bytes
32070 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65  .  .** ^Any atte
32080 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
32090 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
320a0 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
320b0 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
320c0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65  QLITE_MISUSE] be
320d0 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
320e0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
320f0 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
32100 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
32110 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
32120 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
32130 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
32140 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
32150 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
32160 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
32170 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
32180 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
32190 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
321a0 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
321b0 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
321c0 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
321d0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
321e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
321f0 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
32200 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
32210 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
32220 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
32230 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
32240 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
32250 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
32260 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
32270 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
32280 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
32290 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
322a0 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
322b0 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
322c0 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
322d0 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
322e0 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c  ters.  Every SQL
322f0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
32300 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65  entation must be
32310 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
32320 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46   with UTF-8, UTF
32330 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36  -16le, or UTF-16
32340 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d  be.  But some im
32350 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
32360 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66  y be.** more eff
32370 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20  icient with one 
32380 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e  encoding than an
32390 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c  other.  ^An appl
323a0 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69  ication may.** i
323b0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
323c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
323d0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
323e0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
323f0 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
32400 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
32410 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
32420 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
32430 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
32440 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
32450 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
32460 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
32470 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
32480 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
32490 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
324a0 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
324b0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
324c0 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
324d0 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  on..** If there 
324e0 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  is only a single
324f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32500 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63  which does not c
32510 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a  are what text.**
32520 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
32530 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  d, then the four
32540 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  th argument shou
32550 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e  ld be [SQLITE_AN
32560 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  Y]..**.** ^(The 
32570 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
32580 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
32590 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
325a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
325b0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
325c0 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
325d0 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
325e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
325f0 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
32600 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
32610 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
32620 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
32630 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
32640 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
32650 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
32660 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
32670 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
32680 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
32690 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
326a0 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
326b0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
326c0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
326d0 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
326e0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
326f0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
32700 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
32710 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
32720 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
32730 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
32740 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
32750 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
32760 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
32770 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
32780 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
32790 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
327a0 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
327b0 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
327c0 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
327d0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
327e0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
327f0 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
32800 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
32810 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
32820 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
32830 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
32840 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32850 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
32860 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
32870 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
32880 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
32890 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
328a0 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
328b0 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
328c0 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
328d0 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
328e0 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
328f0 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
32900 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
32910 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
32920 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
32930 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
32940 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
32950 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
32960 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32970 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
32980 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
32990 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
329a0 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
329b0 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
329c0 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
329d0 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
329e0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
329f0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
32a00 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
32a10 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
32a20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
32a30 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
32a40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
32a50 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
32a60 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
32a70 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
32a80 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
32a90 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
32aa0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
32ab0 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
32ac0 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
32ad0 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
32ae0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
32af0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
32b00 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
32b10 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
32b20 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
32b30 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
32b40 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
32b50 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
32b60 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
32b70 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
32b80 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
32b90 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
32ba0 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
32bb0 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
32bc0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
32bd0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
32be0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
32bf0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
32c00 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
32c10 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
32c20 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
32c30 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
32c40 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
32c50 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
32c60 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
32c70 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
32c80 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
32c90 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
32ca0 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
32cb0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
32cc0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
32cd0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
32ce0 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
32cf0 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
32d00 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
32d10 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
32d20 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
32d30 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
32d40 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
32d50 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
32d60 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
32d70 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
32d80 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
32d90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32da0 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
32db0 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
32dc0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32dd0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
32de0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
32df0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
32e00 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
32e10 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
32e20 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
32e30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32e40 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
32e50 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
32e60 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
32e70 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
32e80 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
32e90 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
32ea0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
32eb0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
32ec0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
32ed0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
32ee0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
32ef0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
32f00 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
32f10 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
32f20 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
32f30 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
32f40 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
32f50 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
32f60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
32f70 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
32f80 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
32f90 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
32fa0 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54  ntext*).);.SQLIT
32fb0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
32fc0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
32fd0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
32fe0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
32ff0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
33000 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
33010 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
33020 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
33030 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
33040 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
33050 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
33060 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
33070 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
33080 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
33090 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
330a0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
330b0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53  3_context*).);.S
330c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
330d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
330e0 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
330f0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
33100 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
33110 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
33120 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
33130 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
33140 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
33150 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33160 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
33170 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
33180 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
33190 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
331a0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
331b0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
331c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
331d0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
331e0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
331f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
33200 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
33210 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
33220 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
33230 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
33240 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
33250 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
33260 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
33270 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
33280 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
33290 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
332a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
332b0 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
332c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
332d0 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
332e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
332f0 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
33300 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
33310 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
33320 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
33330 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
33340 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
33350 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
33360 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
33370 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
33380 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
33390 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
333a0 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
333b0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
333c0 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
333d0 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
333e0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
333f0 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
33400 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
33410 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
33420 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
33430 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
33440 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
33450 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
33460 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
33470 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
33480 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
33490 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
334a0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
334b0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
334c0 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
334d0 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
334e0 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
334f0 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
33500 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
33510 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
33520 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
33530 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
33540 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 49  CATED.SQLITE_API
33550 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
33560 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
33570 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
33580 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
33590 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
335a0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
335b0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
335c0 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
335d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
335e0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
335f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
33600 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
33610 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
33620 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
33630 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
33640 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
33650 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
33660 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
33670 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
33680 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
33690 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
336a0 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
336b0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
336c0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
336d0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
336e0 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
336f0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
33700 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  t),void*,sqlite3
33710 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
33720 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33730 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
33740 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
33750 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
33760 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
33770 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
33780 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
33790 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
337a0 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
337b0 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
337c0 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
337d0 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
337e0 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
337f0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
33800 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
33810 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
33820 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
33830 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
33840 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
33850 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
33860 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
33870 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
33880 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
33890 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
338a0 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
338b0 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
338c0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
338d0 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
338e0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
338f0 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
33900 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
33910 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
33920 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
33930 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
33940 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
33950 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
33960 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
33970 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
33980 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
33990 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
339a0 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
339b0 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
339c0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
339d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
339e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
339f0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
33a00 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
33a10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
33a20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
33a30 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
33a40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
33a50 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
33a60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
33a70 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
33a80 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
33a90 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
33aa0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
33ab0 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
33ac0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
33ad0 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
33ae0 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
33af0 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20  ept that  these 
33b00 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
33b10 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
33b20 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
33b30 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
33b40 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
33b50 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
33b60 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
33b70 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
33b80 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
33b90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
33ba0 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
33bb0 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
33bc0 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
33bd0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
33be0 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
33bf0 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
33c00 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
33c10 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
33c20 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
33c30 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
33c40 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
33c50 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
33c60 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
33c70 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
33c80 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
33c90 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
33ca0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
33cb0 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
33cc0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
33cd0 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
33ce0 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
33cf0 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
33d00 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
33d10 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
33d20 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
33d30 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
33d40 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
33d50 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
33d60 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
33d70 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
33d80 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
33d90 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
33da0 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
33db0 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
33dc0 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
33dd0 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
33de0 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
33df0 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
33e00 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
33e10 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
33e20 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
33e30 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
33e40 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
33e50 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
33e60 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
33e70 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
33e80 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
33e90 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
33ea0 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
33eb0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
33ec0 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
33ed0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33ee0 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
33ef0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33f00 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
33f10 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
33f20 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
33f30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
33f40 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
33f50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
33f60 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
33f70 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
33f80 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
33f90 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
33fa0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
33fb0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
33fc0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
33fd0 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
33fe0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
33ff0 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
34000 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
34010 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
34020 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
34030 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
34040 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
34050 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
34060 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
34070 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
34080 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34090 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
340a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
340b0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
340c0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
340d0 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  I double sqlite3
340e0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
340f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
34100 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
34110 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
34120 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34130 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
34140 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
34150 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
34160 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
34170 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
34180 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
34190 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
341a0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
341b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
341c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
341d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
341e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
341f0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
34200 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
34210 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
34220 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
34230 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
34240 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
34250 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
34260 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
34270 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
34280 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
34290 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
342a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
342b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
342c0 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
342d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
342e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
342f0 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
34300 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
34310 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74  *.** Implementat
34320 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74  ions of aggregat
34330 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
34340 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74  use this.** rout
34350 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ine to allocate 
34360 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69  memory for stori
34370 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
34380 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
34390 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
343a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
343b0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
343c0 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66   is called .** f
343d0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
343e0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
343f0 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c  on, SQLite.** al
34400 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d  locates N of mem
34410 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
34420 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
34430 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
34440 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77  er.** to the new
34450 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63   memory. ^On sec
34460 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
34470 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
34480 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
34490 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
344a0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
344b0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
344c0 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  nce,.** the same
344d0 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
344e0 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67  ned.  Sqlite3_ag
344f0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
34500 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a  ) is normally.**
34510 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72   called once for
34520 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
34530 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61   of the xStep ca
34540 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20  llback and then 
34550 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65  one.** last time
34560 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c   when the xFinal
34570 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
34580 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f  oked.  ^(When no
34590 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61   rows match.** a
345a0 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  n aggregate quer
345b0 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63  y, the xStep() c
345c0 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61  allback of the a
345d0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
345e0 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
345f0 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c  ion is never cal
34600 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29  led and xFinal()
34610 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74   is called exact
34620 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74  ly once..** In t
34630 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69  hose cases, sqli
34640 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
34650 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65  ntext() might be
34660 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
34670 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72  ** first time fr
34680 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c  om within xFinal
34690 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
346a0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
346b0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
346c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
346d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
346e0 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74  f N is.** less t
346f0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
34700 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d  zero or if a mem
34710 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72  ory allocate err
34720 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a  or occurs..**.**
34730 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66   ^(The amount of
34740 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64   space allocated
34750 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72   by sqlite3_aggr
34760 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
34770 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69  N) is.** determi
34780 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72  ned by the N par
34790 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20  ameter on first 
347a0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e  successful call.
347b0 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a    Changing the.*
347c0 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20  * value of N in 
347d0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
347e0 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
347f0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
34800 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  ithin.** the sam
34810 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
34820 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69  tion instance wi
34830 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68  ll not resize th
34840 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
34850 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20  cation.)^.**.** 
34860 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69  ^SQLite automati
34870 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
34880 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
34890 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
348a0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
348b0 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67  t() when the agg
348c0 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e  regate query con
348d0 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
348e0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
348f0 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79  r must be a copy
34900 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
34910 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
34920 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
34930 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
34940 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
34950 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20  ** to the xStep 
34960 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
34970 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
34980 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
34990 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
349a0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
349b0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
349c0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
349d0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
349e0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
349f0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
34a00 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
34a10 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
34a20 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
34a30 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
34a40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34a50 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
34a60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
34a70 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
34a80 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
34a90 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
34aa0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
34ab0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
34ac0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
34ad0 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
34ae0 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
34af0 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
34b00 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
34b10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
34b20 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
34b30 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
34b40 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
34b50 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
34b60 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
34b70 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
34b80 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
34b90 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
34ba0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
34bb0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
34bc0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
34bd0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
34be0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34bf0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
34c00 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
34c10 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
34c20 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
34c30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
34c40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34c50 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
34c60 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
34c70 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
34c80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
34c90 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
34ca0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
34cb0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
34cc0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
34cd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34ce0 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
34cf0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
34d00 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
34d10 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
34d20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
34d30 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
34d40 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
34d50 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
34d60 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
34d70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
34d80 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53  d function..*/.S
34d90 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
34da0 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
34db0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
34dc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
34dd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34de0 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
34df0 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54  ary Data.**.** T
34e00 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f  he following two
34e10 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
34e20 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72  e used by scalar
34e30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
34e40 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
34e50 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
34e60 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
34e70 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
34e80 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
34e90 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
34ea0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
34eb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
34ec0 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
34ed0 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
34ee0 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
34ef0 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
34f00 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
34f10 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73   preserved. This
34f20 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c   may.** be used,
34f30 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
34f40 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65   add a regular-e
34f50 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
34f60 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e  ng scalar.** fun
34f70 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
34f80 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
34f90 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
34fa0 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20  ssion is stored 
34fb0 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
34fc0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
34fd0 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73  he SQL value pas
34fe0 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c  sed as the regul
34ff0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  ar expression.**
35000 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63   pattern.  The c
35010 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
35020 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
35030 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
35040 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
35050 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
35060 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74  function so that
35070 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61   the original pa
35080 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20  ttern string.** 
35090 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
350a0 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f   be recompiled o
350b0 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  n each invocatio
350c0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
350d0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
350e0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
350f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
35100 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
35110 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
35120 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
35130 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
35140 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
35150 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
35160 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
35170 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35180 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d  nction. ^If no m
35190 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
351a0 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65   ever.** been se
351b0 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72  t for the Nth ar
351c0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75  gument of the fu
351d0 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68  nction, or if th
351e0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
351f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ** function para
35200 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65  meter has change
35210 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61  d since the meta
35220 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a  -data was set,.*
35230 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67  * then sqlite3_g
35240 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74  et_auxdata() ret
35250 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
35260 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
35270 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
35280 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
35290 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61  saves the metada
352a0 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ta.** pointed to
352b0 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61   by its 3rd para
352c0 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74  meter as the met
352d0 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d  adata for the N-
352e0 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
352f0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
35300 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35310 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a  on.  Subsequent.
35320 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
35330 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
35340 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74  ) might return t
35350 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20  his data, if it 
35360 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20  has.** not been 
35370 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49  destroyed..** ^I
35380 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
35390 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  , SQLite will in
353a0 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
353b0 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  tor.** function 
353c0 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68  given by the 4th
353d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
353e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
353f0 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65  a() on.** the me
35400 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20  tadata when the 
35410 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
35420 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
35430 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77   changes.** or w
35440 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
35450 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c  ement completes,
35460 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
35470 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51   first..**.** SQ
35480 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
35490 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63  call the destruc
354a0 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74  tor and drop met
354b0 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20  adata on any.** 
354c0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79  parameter of any
354d0 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79   function at any
354e0 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c   time.  ^The onl
354f0 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74  y guarantee is t
35500 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72  hat.** the destr
35510 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61  uctor will be ca
35520 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  lled before the 
35530 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70  metadata is drop
35540 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ped..**.** ^(In 
35550 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
35560 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
35570 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
35580 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78   calls for.** ex
35590 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61  pressions that a
355a0 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63  re constant at c
355b0 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69  ompile time. Thi
355c0 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72  s includes liter
355d0 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
355e0 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e   [parameters].)^
355f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
35600 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
35610 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
35620 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
35630 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
35640 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
35650 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
35660 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67   void *sqlite3_g
35670 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
35680 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
35690 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20   N);.SQLITE_API 
356a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
356b0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
356c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
356d0 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
356e0 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
356f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
35700 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
35710 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
35720 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
35730 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
35740 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
35750 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
35760 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
35770 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
35780 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
35790 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
357a0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
357b0 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
357c0 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
357d0 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
357e0 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
357f0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
35800 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
35810 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
35820 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
35830 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
35840 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
35850 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
35860 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
35870 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
35880 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
35890 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
358a0 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
358b0 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
358c0 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
358d0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
358e0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
358f0 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
35900 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
35910 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
35920 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
35930 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
35940 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
35950 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
35960 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
35970 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
35980 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
35990 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
359a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
359b0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
359c0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
359d0 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
359e0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
359f0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
35a00 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
35a10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35a20 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
35a30 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
35a40 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  nction.**.** The
35a50 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
35a60 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
35a70 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
35a80 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
35a90 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
35aa0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
35ab0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
35ac0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35ad0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
35ae0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35af0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
35b00 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
35b10 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
35b20 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
35b30 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
35b40 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
35b50 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
35b60 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
35b70 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
35b80 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
35b90 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
35ba0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
35bb0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
35bc0 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
35bd0 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
35be0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
35bf0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
35c00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35c10 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
35c20 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
35c30 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
35c40 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
35c50 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
35c60 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
35c70 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
35c80 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
35c90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
35ca0 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
35cb0 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
35cc0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
35cd0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
35ce0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
35cf0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
35d00 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
35d10 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
35d20 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
35d30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35d40 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
35d50 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
35d60 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
35d70 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
35d80 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
35d90 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
35da0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
35db0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
35dc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
35dd0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
35de0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
35df0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
35e00 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35e10 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
35e20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
35e30 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
35e40 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
35e50 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
35e60 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35e70 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
35e80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35e90 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
35ea0 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
35eb0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
35ec0 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
35ed0 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
35ee0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
35ef0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
35f00 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
35f10 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
35f20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35f30 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
35f40 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
35f50 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
35f60 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
35f70 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
35f80 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
35f90 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
35fa0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
35fb0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
35fc0 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
35fd0 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
35fe0 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
35ff0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36000 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
36010 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
36020 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
36030 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
36040 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
36050 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
36060 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
36070 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
36080 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
36090 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
360a0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
360b0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
360c0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
360d0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
360e0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
360f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
36100 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36110 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
36120 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36130 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
36140 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
36150 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
36160 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
36170 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
36180 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
36190 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
361a0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
361b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
361c0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
361d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
361e0 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
361f0 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
36200 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
36210 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
36220 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
36230 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
36240 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
36250 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
36260 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
36270 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
36280 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
36290 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
362a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
362b0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
362c0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
362d0 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
362e0 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
362f0 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
36300 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
36310 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
36320 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
36330 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
36340 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
36350 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
36360 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
36370 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
36380 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36390 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
363a0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
363b0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
363c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
363d0 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28  3_result_toobig(
363e0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
363f0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
36400 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
36410 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
36420 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
36430 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
36440 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
36450 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36460 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
36470 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
36480 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
36490 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
364a0 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
364b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
364c0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
364d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
364e0 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
364f0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
36500 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
36510 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36520 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36530 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
36540 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
36550 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
36560 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
36570 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36580 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
36590 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
365a0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
365b0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
365c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
365d0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
365e0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
365f0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
36600 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
36610 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
36620 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36630 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
36640 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
36650 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
36660 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36670 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36680 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
36690 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
366a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
366b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
366c0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
366d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
366e0 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
366f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
36700 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
36710 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
36720 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
36730 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36740 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36750 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
36760 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
36770 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
36780 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
36790 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
367a0 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
367b0 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
367c0 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
367d0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c  ctively..** ^SQL
367e0 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
367f0 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
36800 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
36810 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
36820 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
36830 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
36840 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
36850 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
36860 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
36870 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36880 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
36890 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
368a0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
368b0 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
368c0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
368d0 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
368e0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
368f0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
36900 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
36910 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
36920 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
36930 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
36940 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
36950 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
36960 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
36970 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
36980 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
36990 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
369a0 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
369b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
369c0 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
369d0 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74  on result.  If t
369e0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
369f0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
36a00 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73  , then it.** mus
36a10 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
36a20 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74  fset into the st
36a30 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e  ring where the N
36a40 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
36a50 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66  uld.** appear if
36a60 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
36a70 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64  e NUL terminated
36a80 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
36a90 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a  aracters occur.*
36aa0 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  * in the string 
36ab0 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74  at a byte offset
36ac0 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68   that is less th
36ad0 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  an the value of 
36ae0 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d  the 3rd.** param
36af0 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  eter, then the r
36b00 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
36b10 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62  will contain emb
36b20 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74  edded NULs and t
36b30 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20  he.** result of 
36b40 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72  expressions oper
36b50 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73  ating on strings
36b60 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
36b70 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
36b80 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
36b90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
36ba0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36bb0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
36bc0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
36bd0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
36be0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
36bf0 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
36c00 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
36c10 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
36c20 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
36c30 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
36c40 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
36c50 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
36c60 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
36c70 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
36c80 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
36c90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36ca0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
36cb0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   to.** sqlite3_r
36cc0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
36cd0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
36ce0 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
36cf0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
36d00 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
36d10 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
36d20 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
36d30 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
36d40 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
36d50 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
36d60 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72  he parameter nor
36d70 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
36d80 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e  or on the conten
36d90 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73  t.** when it has
36da0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
36db0 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
36dc0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
36dd0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
36de0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36df0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
36e00 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
36e10 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
36e20 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
36e30 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
36e40 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
36e50 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
36e60 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
36e70 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
36e80 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
36e90 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
36ea0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
36eb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36ec0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
36ed0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
36ee0 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
36ef0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
36f00 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
36f10 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
36f20 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
36f30 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
36f40 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
36f50 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
36f60 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
36f70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
36f80 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
36f90 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
36fa0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
36fb0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
36fc0 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
36fd0 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
36fe0 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
36ff0 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
37000 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
37010 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
37020 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
37030 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
37040 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f  harm..** ^A [pro
37050 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
37060 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
37070 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
37080 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
37090 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
370a0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
370b0 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
370c0 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
370d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
370e0 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
370f0 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
37100 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
37110 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
37120 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
37130 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
37140 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
37150 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
37160 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
37170 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
37180 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
37190 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
371a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
371b0 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
371c0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
371d0 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
371e0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
371f0 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
37200 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
37210 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
37220 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
37230 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
37240 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
37250 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  ouble(sqlite3_co
37260 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b  ntext*, double);
37270 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
37280 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37290 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
372a0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
372b0 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  ar*, int);.SQLIT
372c0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
372d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
372e0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
372f0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
37300 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
37310 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
37320 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
37330 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
37340 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
37350 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
37360 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
37370 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37380 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  *);.SQLITE_API v
37390 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
373a0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
373b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
373c0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
373d0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
373e0 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
373f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
37400 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
37410 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37420 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
37430 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
37440 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41  int64);.SQLITE_A
37450 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
37460 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
37470 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
37480 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
37490 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
374a0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
374b0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
374c0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
374d0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
374e0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
374f0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
37500 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37510 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
37520 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
37530 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
37540 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37550 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  t_text16le(sqlit
37560 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
37570 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
37580 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
37590 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
375a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
375b0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
375c0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
375d0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
375e0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
375f0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
37600 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
37610 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37620 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
37630 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
37640 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37650 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
37660 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
37670 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
37680 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
37690 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
376a0 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  nces.**.** ^Thes
376b0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
376c0 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
376d0 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
376e0 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
376f0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
37700 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
37710 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
37720 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
37730 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
37740 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
37750 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
37760 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
37770 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37780 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
37790 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
377a0 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
377b0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
377c0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
377d0 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
377e0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
377f0 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
37800 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
37810 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
37820 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
37830 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
37840 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
37850 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
37860 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
37870 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
37880 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
37890 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
378a0 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
378b0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
378c0 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
378d0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
378e0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
378f0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
37900 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
37910 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
37920 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
37930 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
37940 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
37950 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
37960 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
37970 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
37980 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
37990 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
379a0 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
379b0 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
379c0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
379d0 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
379e0 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
379f0 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
37a00 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
37a10 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
37a20 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
37a30 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
37a40 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
37a50 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74   value for eText
37a60 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e  Rep forces strin
37a70 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f  gs to begin.** o
37a80 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61  n an even byte a
37a90 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ddress..**.** ^T
37aa0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
37ab0 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20  nt, pArg, is an 
37ac0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
37ad0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
37ae0 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75   passed.** throu
37af0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
37b00 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
37b10 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37b20 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
37b30 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
37b40 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63  gument, xCallbac
37b50 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  k, is a pointer 
37b60 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
37b70 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d   function..** ^M
37b80 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e  ultiple collatin
37b90 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20  g functions can 
37ba0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73  be registered us
37bb0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
37bc0 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69  e but.** with di
37bd0 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
37be0 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
37bf0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
37c00 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e  whichever.** fun
37c10 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74  ction requires t
37c20 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
37c30 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72  of data transfor
37c40 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  mation..** ^If t
37c50 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67  he xCallback arg
37c60 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68  ument is NULL th
37c70 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  en the collating
37c80 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
37c90 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20  deleted.  ^When 
37ca0 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  all collating fu
37cb0 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74  nctions having t
37cc0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  he same name are
37cd0 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61   deleted,.** tha
37ce0 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e  t collation is n
37cf0 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e  o longer usable.
37d00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c  .**.** ^The coll
37d10 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
37d20 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
37d30 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f  ed with a copy o
37d40 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61  f the pArg .** a
37d50 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
37d60 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68  pointer and with
37d70 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20   two strings in 
37d80 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
37d90 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
37da0 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
37db0 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69  nt.  The collati
37dc0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
37dd0 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e   return an.** in
37de0 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65  teger that is ne
37df0 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72  gative, zero, or
37e00 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20   positive.** if 
37e10 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
37e20 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65   is less than, e
37e30 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
37e40 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
37e50 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ond,.** respecti
37e60 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69  vely.  A collati
37e70 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
37e80 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
37e90 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a  he same answer.*
37ea0 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65  * given the same
37eb0 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f   inputs.  If two
37ec0 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69   or more collati
37ed0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
37ee0 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74   registered.** t
37ef0 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61  o the same colla
37f00 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67  tion name (using
37f10 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
37f20 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e  Rep values) then
37f30 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76   all.** must giv
37f40 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20  e an equivalent 
37f50 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f  answer when invo
37f60 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c  ked with equival
37f70 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  ent strings..** 
37f80 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
37f90 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79  nction must obey
37fa0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70   the following p
37fb0 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c  roperties for al
37fc0 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20  l.** strings A, 
37fd0 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20  B, and C:.**.** 
37fe0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  <ol>.** <li> If 
37ff0 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a  A==B then B==A..
38000 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
38010 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d  and B==C then A=
38020 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =C..** <li> If A
38030 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b  &lt;B THEN B&gt;
38040 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  A..** <li> If A&
38050 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20  lt;B and B&lt;C 
38060 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20  then A&lt;C..** 
38070 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  </ol>.**.** If a
38080 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
38090 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66  ion fails any of
380a0 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74   the above const
380b0 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a  raints and that.
380c0 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ** collating fun
380d0 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74  ction is  regist
380e0 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74  ered and used, t
380f0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
38100 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73   of SQLite.** is
38110 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
38120 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
38130 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
38140 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
38150 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
38160 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69  ollation().** wi
38170 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20  th the addition 
38180 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f  that the xDestro
38190 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  y callback is in
381a0 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68  voked on pArg wh
381b0 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  en.** the collat
381c0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
381d0 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c  deleted..** ^Col
381e0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
381f0 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65   are deleted whe
38200 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
38210 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a  idden by later.*
38220 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63  * calls to the c
38230 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
38240 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
38250 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  hen the.** [data
38260 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38270 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
38280 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
38290 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  )]..**.** ^The x
382a0 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
382b0 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63   is <u>not</u> c
382c0 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a  alled if the .**
382d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
382e0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66  collation_v2() f
382f0 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  unction fails.  
38300 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
38310 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  t invoke.** sqli
38320 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
38330 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61  tion_v2() with a
38340 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72   non-NULL xDestr
38350 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  oy argument shou
38360 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65  ld .** check the
38370 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64   return code and
38380 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
38390 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
383a0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d   pointer.** them
383b0 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68  selves rather th
383c0 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c  an expecting SQL
383d0 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68  ite to deal with
383e0 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a   it for them..**
383f0 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65   This is differe
38400 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74  nt from every ot
38410 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
38420 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e  face.  The incon
38430 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20  sistency .** is 
38440 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20  unfortunate but 
38450 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
38460 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
38470 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a  ng backwards .**
38480 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
38490 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
384a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
384b0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e  ion_needed()] an
384c0 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  d [sqlite3_colla
384d0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d  tion_needed16()]
384e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
384f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
38500 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
38510 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
38520 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
38530 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
38540 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
38550 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
38560 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
38570 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
38580 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54   void*).);.SQLIT
38590 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
385a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
385b0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
385c0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
385d0 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
385e0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
385f0 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
38600 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
38610 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
38620 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
38630 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
38640 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51  oy)(void*).);.SQ
38650 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
38660 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
38670 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
38680 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f  e3*, .  const vo
38690 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74  id *zName,.  int
386a0 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
386b0 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
386c0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
386d0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
386e0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
386f0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
38700 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  3REF: Collation 
38710 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73  Needed Callbacks
38720 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64  .**.** ^To avoid
38730 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
38740 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
38750 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
38760 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
38770 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
38780 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
38790 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
387a0 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
387b0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [d