System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact d5cd1535053a50aa8633725e3595740b33709ac5:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  ** This file is 
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20  an amalgamation 
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65  of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20   C source files 
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76  from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 38 2e 34 2e 31 2e 20  ersion 3.8.4.1. 
00b0: 20 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c   By combining al
00c0: 6c 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c  l the individual
00d0: 20 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e   C code files in
00e0: 74 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67  to this .** sing
00f0: 6c 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74  le large file, t
0100: 68 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63  he entire code c
0110: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61  an be compiled a
0120: 73 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73  s a single trans
0130: 6c 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20  lation.** unit. 
0140: 20 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e   This allows man
0150: 79 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64  y compilers to d
0160: 6f 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  o optimizations 
0170: 74 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62  that would not b
0180: 65 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66  e.** possible if
0190: 20 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20   the files were 
01a0: 63 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74  compiled separat
01b0: 65 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63  ely.  Performanc
01c0: 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a  e improvements.*
01d0: 2a 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20  * of 5% or more 
01e0: 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65  are commonly see
01f0: 6e 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  n when SQLite is
0200: 20 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73   compiled as a s
0210: 69 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61  ingle.** transla
0220: 74 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a  tion unit..**.**
0230: 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c   This file is al
0240: 6c 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f  l you need to co
0250: 6d 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54  mpile SQLite.  T
0260: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20  o use SQLite in 
0270: 6f 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d  other.** program
0280: 73 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73  s, you need this
0290: 20 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73   file and the "s
02a0: 71 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72  qlite3.h" header
02b0: 20 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e   file that defin
02c0: 65 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61  es.** the progra
02d0: 6d 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  mming interface 
02e0: 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  to the SQLite li
02f0: 62 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20  brary.  (If you 
0300: 64 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20  do not have .** 
0310: 74 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20  the "sqlite3.h" 
0320: 68 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68  header file at h
0330: 61 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69  and, you will fi
0340: 6e 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64  nd a copy embedd
0350: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
0360: 20 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69   text of this fi
0370: 6c 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20  le.  Search for 
0380: 22 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69  "Begin file sqli
0390: 74 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74  te3.h" to find t
03a0: 68 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74  he start.** of t
03b0: 68 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69  he embedded sqli
03c0: 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c  te3.h header fil
03d0: 65 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63  e.) Additional c
03e0: 6f 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65  ode files may be
03f0: 20 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f   needed.** if yo
0400: 75 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72  u want a wrapper
0410: 20 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51   to interface SQ
0420: 4c 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63  Lite with your c
0430: 68 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d  hoice of program
0440: 6d 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65  ming.** language
0450: 2e 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74  . The code for t
0460: 68 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d  he "sqlite3" com
0470: 6d 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20  mand-line shell 
0480: 69 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20  is also in a.** 
0490: 73 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54  separate file. T
04a0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e  his file contain
04b0: 73 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20  s only code for 
04c0: 74 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20  the core SQLite 
04d0: 6c 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66  library..*/.#def
04e0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20  ine SQLITE_CORE 
04f0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
0500: 5f 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a  _AMALGAMATION 1.
0510: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50  #ifndef SQLITE_P
0520: 52 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20  RIVATE.# define 
0530: 53 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73  SQLITE_PRIVATE s
0540: 74 61 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66  tatic.#endif.#if
0550: 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a  ndef SQLITE_API.
0560: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
0570: 41 50 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a  API.#endif./****
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e  ********** Begin
0590: 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e   file sqliteInt.
05a0: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  h **************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a  *********/./*.**
05d0: 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20   2001 September 
05e0: 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  15.**.** The aut
05f0: 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f  hor disclaims co
0600: 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20  pyright to this 
0610: 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e  source code.  In
0620: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c   place of.** a l
0630: 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72  egal notice, her
0640: 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a  e is a blessing:
0650: 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f  .**.**    May yo
0660: 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f  u do good and no
0670: 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61  t evil..**    Ma
0680: 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69  y you find forgi
0690: 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73  veness for yours
06a0: 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20  elf and forgive 
06b0: 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61  others..**    Ma
06c0: 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65  y you share free
06d0: 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67  ly, never taking
06e0: 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67   more than you g
06f0: 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a  ive..**.********
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0740: 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e  *.** Internal in
0750: 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69  terface definiti
0760: 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a  ons for SQLite..
0770: 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53  **.*/.#ifndef _S
0780: 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66  QLITEINT_H_.#def
0790: 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48  ine _SQLITEINT_H
07a0: 5f 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23  _../*.** These #
07b0: 64 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65  defines should e
07c0: 6e 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20  nable >2GB file 
07d0: 73 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58  support on POSIX
07e0: 20 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   if the.** under
07f0: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
0800: 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20  system supports 
0810: 69 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c  it.  If the OS l
0820: 61 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69  acks.** large fi
0830: 6c 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69  le support, or i
0840: 66 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64  f the OS is wind
0850: 6f 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c  ows, these shoul
0860: 64 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a  d be no-ops..**.
0870: 2a 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a  ** Ticket #2739:
0880: 20 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45    The _LARGEFILE
0890: 5f 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75  _SOURCE macro mu
08a0: 73 74 20 61 70 70 65 61 72 20 62 65 66 6f 72 65  st appear before
08b0: 20 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23   any.** system #
08c0: 69 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65  includes.  Hence
08d0: 2c 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20  , this block of 
08e0: 63 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68 65  code must be the
08f0: 20 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63   very first.** c
0900: 6f 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63  ode in all sourc
0910: 65 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c  e files..**.** L
0920: 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72  arge file suppor
0930: 74 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65  t can be disable
0940: 64 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51  d using the -DSQ
0950: 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53  LITE_DISABLE_LFS
0960: 20 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68   switch.** on th
0970: 65 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61  e compiler comma
0980: 6e 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69  nd line.  This i
0990: 73 20 6e 65 63 65 73 73 61 72 79 20 69 66 20 79  s necessary if y
09a0: 6f 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67  ou are compiling
09b0: 0a 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20  .** on a recent 
09c0: 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64  machine (ex: Red
09d0: 20 48 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f   Hat 7.2) but yo
09e0: 75 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65  u want your code
09f0: 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61   to work.** on a
0a00: 6e 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20  n older machine 
0a10: 28 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30  (ex: Red Hat 6.0
0a20: 29 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69  ).  If you compi
0a30: 6c 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e  le on Red Hat 7.
0a40: 32 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69  2.** without thi
0a50: 73 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73  s option, LFS is
0a60: 20 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46   enable.  But LF
0a70: 53 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74  S does not exist
0a80: 20 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a   in the kernel.*
0a90: 2a 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30  * in Red Hat 6.0
0aa0: 2c 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f  , so the code wo
0ab0: 6e 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65  n't work.  Hence
0ac0: 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69  , for maximum bi
0ad0: 6e 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c  nary.** portabil
0ae0: 69 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f  ity you should o
0af0: 6d 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 54  mit LFS..**.** T
0b00: 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
0b10: 67 72 61 70 68 20 77 61 73 20 77 72 69 74 74 65  graph was writte
0b20: 6e 20 69 6e 20 32 30 30 35 2e 20 20 28 54 68 69  n in 2005.  (Thi
0b30: 73 20 70 61 72 61 67 72 61 70 68 20 69 73 20 77  s paragraph is w
0b40: 72 69 74 74 65 6e 0a 2a 2a 20 6f 6e 20 32 30 30  ritten.** on 200
0b50: 38 2d 31 31 2d 32 38 2e 29 20 54 68 65 73 65 20  8-11-28.) These 
0b60: 64 61 79 73 2c 20 61 6c 6c 20 4c 69 6e 75 78 20  days, all Linux 
0b70: 6b 65 72 6e 65 6c 73 20 73 75 70 70 6f 72 74 20  kernels support 
0b80: 6c 61 72 67 65 20 66 69 6c 65 73 2c 20 73 6f 0a  large files, so.
0b90: 2a 2a 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  ** you should pr
0ba0: 6f 62 61 62 6c 79 20 6c 65 61 76 65 20 4c 46 53  obably leave LFS
0bb0: 20 65 6e 61 62 6c 65 64 2e 20 20 42 75 74 20 73   enabled.  But s
0bc0: 6f 6d 65 20 65 6d 62 65 64 64 65 64 20 70 6c 61  ome embedded pla
0bd0: 74 66 6f 72 6d 73 20 6d 69 67 68 74 0a 2a 2a 20  tforms might.** 
0be0: 6c 61 63 6b 20 4c 46 53 20 69 6e 20 77 68 69 63  lack LFS in whic
0bf0: 68 20 63 61 73 65 20 74 68 65 20 53 51 4c 49 54  h case the SQLIT
0c00: 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20 6d 61  E_DISABLE_LFS ma
0c10: 63 72 6f 20 6d 69 67 68 74 20 73 74 69 6c 6c 20  cro might still 
0c20: 62 65 20 75 73 65 66 75 6c 2e 0a 2a 2a 0a 2a 2a  be useful..**.**
0c30: 20 53 69 6d 69 6c 61 72 20 69 73 20 74 72 75 65   Similar is true
0c40: 20 66 6f 72 20 4d 61 63 20 4f 53 20 58 2e 20 20   for Mac OS X.  
0c50: 4c 46 53 20 69 73 20 6f 6e 6c 79 20 73 75 70 70  LFS is only supp
0c60: 6f 72 74 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20  orted on Mac OS 
0c70: 58 20 39 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a  X 9 and later..*
0c80: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0c90: 5f 44 49 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64  _DISABLE_LFS.# d
0ca0: 65 66 69 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c  efine _LARGE_FIL
0cb0: 45 20 20 20 20 20 20 20 31 0a 23 20 69 66 6e 64  E       1.# ifnd
0cc0: 65 66 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f  ef _FILE_OFFSET_
0cd0: 42 49 54 53 0a 23 20 20 20 64 65 66 69 6e 65 20  BITS.#   define 
0ce0: 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54  _FILE_OFFSET_BIT
0cf0: 53 20 36 34 0a 23 20 65 6e 64 69 66 0a 23 20 64  S 64.# endif.# d
0d00: 65 66 69 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45  efine _LARGEFILE
0d10: 5f 53 4f 55 52 43 45 20 31 0a 23 65 6e 64 69 66  _SOURCE 1.#endif
0d20: 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47  ../*.** For MinG
0d30: 57 2c 20 63 68 65 63 6b 20 74 6f 20 73 65 65 20  W, check to see 
0d40: 69 66 20 77 65 20 63 61 6e 20 69 6e 63 6c 75 64  if we can includ
0d50: 65 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  e the header fil
0d60: 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 74 73  e containing its
0d70: 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 69 6e 66 6f  .** version info
0d80: 72 6d 61 74 69 6f 6e 2c 20 61 6d 6f 6e 67 20 6f  rmation, among o
0d90: 74 68 65 72 20 74 68 69 6e 67 73 2e 20 20 4e 6f  ther things.  No
0da0: 72 6d 61 6c 6c 79 2c 20 74 68 69 73 20 69 6e 74  rmally, this int
0db0: 65 72 6e 61 6c 20 4d 69 6e 47 57 0a 2a 2a 20 68  ernal MinGW.** h
0dc0: 65 61 64 65 72 20 66 69 6c 65 20 77 6f 75 6c 64  eader file would
0dd0: 20 5b 6f 6e 6c 79 5d 20 62 65 20 69 6e 63 6c 75   [only] be inclu
0de0: 64 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ded automaticall
0df0: 79 20 62 79 20 6f 74 68 65 72 20 4d 69 6e 47 57  y by other MinGW
0e00: 20 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65 73   header.** files
0e10: 3b 20 68 6f 77 65 76 65 72 2c 20 74 68 65 20 63  ; however, the c
0e20: 6f 6e 74 61 69 6e 65 64 20 76 65 72 73 69 6f 6e  ontained version
0e30: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
0e40: 6e 6f 77 20 72 65 71 75 69 72 65 64 20 62 79 20  now required by 
0e50: 74 68 69 73 0a 2a 2a 20 68 65 61 64 65 72 20 66  this.** header f
0e60: 69 6c 65 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ile to work arou
0e70: 6e 64 20 62 69 6e 61 72 79 20 63 6f 6d 70 61 74  nd binary compat
0e80: 69 62 69 6c 69 74 79 20 69 73 73 75 65 73 20 28  ibility issues (
0e90: 73 65 65 20 62 65 6c 6f 77 29 20 61 6e 64 0a 2a  see below) and.*
0ea0: 2a 20 74 68 69 73 20 69 73 20 74 68 65 20 6f 6e  * this is the on
0eb0: 6c 79 20 6b 6e 6f 77 6e 20 77 61 79 20 74 6f 20  ly known way to 
0ec0: 72 65 6c 69 61 62 6c 79 20 6f 62 74 61 69 6e 20  reliably obtain 
0ed0: 69 74 2e 20 20 54 68 69 73 20 65 6e 74 69 72 65  it.  This entire
0ee0: 20 23 69 66 20 62 6c 6f 63 6b 0a 2a 2a 20 77 6f   #if block.** wo
0ef0: 75 6c 64 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  uld be completel
0f00: 79 20 75 6e 6e 65 63 65 73 73 61 72 79 20 69 66  y unnecessary if
0f10: 20 74 68 65 72 65 20 77 61 73 20 61 6e 79 20 6f   there was any o
0f20: 74 68 65 72 20 77 61 79 20 6f 66 20 64 65 74 65  ther way of dete
0f30: 63 74 69 6e 67 0a 2a 2a 20 4d 69 6e 47 57 20 76  cting.** MinGW v
0f40: 69 61 20 74 68 65 69 72 20 70 72 65 70 72 6f 63  ia their preproc
0f50: 65 73 73 6f 72 20 28 65 2e 67 2e 20 69 66 20 74  essor (e.g. if t
0f60: 68 65 79 20 63 75 73 74 6f 6d 69 7a 65 64 20 74  hey customized t
0f70: 68 65 69 72 20 47 43 43 20 74 6f 20 64 65 66 69  heir GCC to defi
0f80: 6e 65 0a 2a 2a 20 73 6f 6d 65 20 4d 69 6e 47 57  ne.** some MinGW
0f90: 2d 73 70 65 63 69 66 69 63 20 6d 61 63 72 6f 73  -specific macros
0fa0: 29 2e 20 20 57 68 65 6e 20 63 6f 6d 70 69 6c 69  ).  When compili
0fb0: 6e 67 20 66 6f 72 20 4d 69 6e 47 57 2c 20 65 69  ng for MinGW, ei
0fc0: 74 68 65 72 20 74 68 65 0a 2a 2a 20 5f 48 41 56  ther the.** _HAV
0fd0: 45 5f 4d 49 4e 47 57 5f 48 20 6f 72 20 5f 48 41  E_MINGW_H or _HA
0fe0: 56 45 5f 5f 4d 49 4e 47 57 5f 48 20 28 6e 6f 74  VE__MINGW_H (not
0ff0: 65 20 74 68 65 20 65 78 74 72 61 20 75 6e 64 65  e the extra unde
1000: 72 73 63 6f 72 65 29 20 6d 61 63 72 6f 20 6d 75  rscore) macro mu
1010: 73 74 20 62 65 0a 2a 2a 20 64 65 66 69 6e 65 64  st be.** defined
1020: 3b 20 6f 74 68 65 72 77 69 73 65 2c 20 64 65 74  ; otherwise, det
1030: 65 63 74 69 6f 6e 20 6f 66 20 63 6f 6e 64 69 74  ection of condit
1040: 69 6f 6e 73 20 73 70 65 63 69 66 69 63 20 74 6f  ions specific to
1050: 20 4d 69 6e 47 57 20 77 69 6c 6c 20 62 65 0a 2a   MinGW will be.*
1060: 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2f 0a 23  * disabled..*/.#
1070: 69 66 20 64 65 66 69 6e 65 64 28 5f 48 41 56 45  if defined(_HAVE
1080: 5f 4d 49 4e 47 57 5f 48 29 0a 23 20 69 6e 63 6c  _MINGW_H).# incl
1090: 75 64 65 20 22 6d 69 6e 67 77 2e 68 22 0a 23 65  ude "mingw.h".#e
10a0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 48 41 56  lif defined(_HAV
10b0: 45 5f 5f 4d 49 4e 47 57 5f 48 29 0a 23 20 69 6e  E__MINGW_H).# in
10c0: 63 6c 75 64 65 20 22 5f 6d 69 6e 67 77 2e 68 22  clude "_mingw.h"
10d0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 46  .#endif../*.** F
10e0: 6f 72 20 4d 69 6e 47 57 20 76 65 72 73 69 6f 6e  or MinGW version
10f0: 20 34 2e 78 20 28 61 6e 64 20 68 69 67 68 65 72   4.x (and higher
1100: 29 2c 20 63 68 65 63 6b 20 74 6f 20 73 65 65 20  ), check to see 
1110: 69 66 20 74 68 65 20 5f 55 53 45 5f 33 32 42 49  if the _USE_32BI
1120: 54 5f 54 49 4d 45 5f 54 0a 2a 2a 20 64 65 66 69  T_TIME_T.** defi
1130: 6e 65 20 69 73 20 72 65 71 75 69 72 65 64 20 74  ne is required t
1140: 6f 20 6d 61 69 6e 74 61 69 6e 20 62 69 6e 61 72  o maintain binar
1150: 79 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  y compatibility 
1160: 77 69 74 68 20 74 68 65 20 4d 53 56 43 20 72 75  with the MSVC ru
1170: 6e 74 69 6d 65 0a 2a 2a 20 6c 69 62 72 61 72 79  ntime.** library
1180: 20 69 6e 20 75 73 65 20 28 65 2e 67 2e 20 66 6f   in use (e.g. fo
1190: 72 20 57 69 6e 64 6f 77 73 20 58 50 29 2e 0a 2a  r Windows XP)..*
11a0: 2f 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28 5f  /.#if !defined(_
11b0: 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f 54  USE_32BIT_TIME_T
11c0: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 55  ) && !defined(_U
11d0: 53 45 5f 36 34 42 49 54 5f 54 49 4d 45 5f 54 29  SE_64BIT_TIME_T)
11e0: 20 26 26 20 5c 0a 20 20 20 20 64 65 66 69 6e 65   && \.    define
11f0: 64 28 5f 57 49 4e 33 32 29 20 26 26 20 21 64 65  d(_WIN32) && !de
1200: 66 69 6e 65 64 28 5f 57 49 4e 36 34 29 20 26 26  fined(_WIN64) &&
1210: 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f   \.    defined(_
1220: 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52 5f 56 45 52  _MINGW_MAJOR_VER
1230: 53 49 4f 4e 29 20 26 26 20 5f 5f 4d 49 4e 47 57  SION) && __MINGW
1240: 5f 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 20 3e  _MAJOR_VERSION >
1250: 3d 20 34 20 26 26 20 5c 0a 20 20 20 20 64 65 66  = 4 && \.    def
1260: 69 6e 65 64 28 5f 5f 4d 53 56 43 52 54 5f 5f 29  ined(__MSVCRT__)
1270: 0a 23 20 64 65 66 69 6e 65 20 5f 55 53 45 5f 33  .# define _USE_3
1280: 32 42 49 54 5f 54 49 4d 45 5f 54 0a 23 65 6e 64  2BIT_TIME_T.#end
1290: 69 66 0a 0a 2f 2a 20 54 68 65 20 70 75 62 6c 69  if../* The publi
12a0: 63 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  c SQLite interfa
12b0: 63 65 2e 20 20 54 68 65 20 5f 46 49 4c 45 5f 4f  ce.  The _FILE_O
12c0: 46 46 53 45 54 5f 42 49 54 53 20 6d 61 63 72 6f  FFSET_BITS macro
12d0: 20 6d 75 73 74 20 61 70 70 65 61 72 0a 2a 2a 20   must appear.** 
12e0: 66 69 72 73 74 20 69 6e 20 51 4e 58 2e 20 20 41  first in QNX.  A
12f0: 6c 73 6f 2c 20 74 68 65 20 5f 55 53 45 5f 33 32  lso, the _USE_32
1300: 42 49 54 5f 54 49 4d 45 5f 54 20 6d 61 63 72 6f  BIT_TIME_T macro
1310: 20 6d 75 73 74 20 61 70 70 65 61 72 20 66 69 72   must appear fir
1320: 73 74 20 66 6f 72 0a 2a 2a 20 4d 69 6e 47 57 2e  st for.** MinGW.
1330: 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
1340: 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69  *** Include sqli
1350: 74 65 33 2e 68 20 69 6e 20 74 68 65 20 6d 69 64  te3.h in the mid
1360: 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49 6e 74  dle of sqliteInt
1370: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .h *************
1380: 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  **/./***********
1390: 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73  *** Begin file s
13a0: 71 6c 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a  qlite3.h *******
13b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13d0: 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31 20 53  **/./*.** 2001 S
13e0: 65 70 74 65 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a  eptember 15.**.*
13f0: 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64 69 73  * The author dis
1400: 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67 68 74  claims copyright
1410: 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63 65 20   to this source 
1420: 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63 65 20  code.  In place 
1430: 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f  of.** a legal no
1440: 74 69 63 65 2c 20 68 65 72 65 20 69 73 20 61 20  tice, here is a 
1450: 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20  blessing:.**.** 
1460: 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f     May you do go
1470: 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e  od and not evil.
1480: 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 66  .**    May you f
1490: 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73 73 20  ind forgiveness 
14a0: 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61 6e 64  for yourself and
14b0: 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72 73 2e   forgive others.
14c0: 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 73  .**    May you s
14d0: 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e 65 76  hare freely, nev
14e0: 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74  er taking more t
14f0: 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a  han you give..**
1500: 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .***************
1510: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1520: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1530: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1540: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68  **********.** Th
1550: 69 73 20 68 65 61 64 65 72 20 66 69 6c 65 20 64  is header file d
1560: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
1570: 66 61 63 65 20 74 68 61 74 20 74 68 65 20 53 51  face that the SQ
1580: 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20  Lite library.** 
1590: 70 72 65 73 65 6e 74 73 20 74 6f 20 63 6c 69 65  presents to clie
15a0: 6e 74 20 70 72 6f 67 72 61 6d 73 2e 20 20 49 66  nt programs.  If
15b0: 20 61 20 43 2d 66 75 6e 63 74 69 6f 6e 2c 20 73   a C-function, s
15c0: 74 72 75 63 74 75 72 65 2c 20 64 61 74 61 74 79  tructure, dataty
15d0: 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73 74 61  pe,.** or consta
15e0: 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 20 64 6f  nt definition do
15f0: 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 69 6e  es not appear in
1600: 20 74 68 69 73 20 66 69 6c 65 2c 20 74 68 65 6e   this file, then
1610: 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 61 20   it is.** not a 
1620: 70 75 62 6c 69 73 68 65 64 20 41 50 49 20 6f 66  published API of
1630: 20 53 51 4c 69 74 65 2c 20 69 73 20 73 75 62 6a   SQLite, is subj
1640: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
1650: 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c  thout.** notice,
1660: 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20   and should not 
1670: 62 65 20 72 65 66 65 72 65 6e 63 65 64 20 62 79  be referenced by
1680: 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74 20 75   programs that u
1690: 73 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  se SQLite..**.**
16a0: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 64 65 66   Some of the def
16b0: 69 6e 69 74 69 6f 6e 73 20 74 68 61 74 20 61 72  initions that ar
16c0: 65 20 69 6e 20 74 68 69 73 20 66 69 6c 65 20 61  e in this file a
16d0: 72 65 20 6d 61 72 6b 65 64 20 61 73 0a 2a 2a 20  re marked as.** 
16e0: 22 65 78 70 65 72 69 6d 65 6e 74 61 6c 22 2e 20  "experimental". 
16f0: 20 45 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   Experimental in
1700: 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 72  terfaces are nor
1710: 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66 65 61  mally new.** fea
1720: 74 75 72 65 73 20 72 65 63 65 6e 74 6c 79 20 61  tures recently a
1730: 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65 2e 20  dded to SQLite. 
1740: 20 57 65 20 64 6f 20 6e 6f 74 20 61 6e 74 69 63   We do not antic
1750: 69 70 61 74 65 20 63 68 61 6e 67 65 73 0a 2a 2a  ipate changes.**
1760: 20 74 6f 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   to experimental
1770: 20 69 6e 74 65 72 66 61 63 65 73 20 62 75 74 20   interfaces but 
1780: 72 65 73 65 72 76 65 20 74 68 65 20 72 69 67 68  reserve the righ
1790: 74 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f 72 20  t to make minor 
17a0: 63 68 61 6e 67 65 73 0a 2a 2a 20 69 66 20 65 78  changes.** if ex
17b0: 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20 75 73  perience from us
17c0: 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64 22 20  e "in the wild" 
17d0: 73 75 67 67 65 73 74 20 73 75 63 68 20 63 68 61  suggest such cha
17e0: 6e 67 65 73 20 61 72 65 20 70 72 75 64 65 6e 74  nges are prudent
17f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 66 69  ..**.** The offi
1800: 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67 65 20  cial C-language 
1810: 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  API documentatio
1820: 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69 73 20  n for SQLite is 
1830: 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f 6d 20  derived.** from 
1840: 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68 69 73  comments in this
1850: 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66 69 6c   file.  This fil
1860: 65 20 69 73 20 74 68 65 20 61 75 74 68 6f 72 69  e is the authori
1870: 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a 2a 2a  tative source.**
1880: 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65 20 69   on how SQLite i
1890: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
18a0: 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61 74 65  ppose to operate
18b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ..**.** The name
18c0: 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 75 6e   of this file un
18d0: 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  der configuratio
18e0: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69 73 20  n management is 
18f0: 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a  "sqlite.h.in"..*
1900: 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d  * The makefile m
1910: 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20  akes some minor 
1920: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69 73 20  changes to this 
1930: 66 69 6c 65 20 28 73 75 63 68 20 61 73 20 69 6e  file (such as in
1940: 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76  serting.** the v
1950: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61  ersion number) a
1960: 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73 20 6e  nd changes its n
1970: 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65 33 2e  ame to "sqlite3.
1980: 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  h" as.** part of
1990: 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f 63 65   the build proce
19a0: 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f  ss..*/.#ifndef _
19b0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 64 65 66 69  SQLITE3_H_.#defi
19c0: 6e 65 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ne _SQLITE3_H_.#
19d0: 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72 67 2e  include <stdarg.
19e0: 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64 65 64  h>     /* Needed
19f0: 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e 69 74   for the definit
1a00: 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a  ion of va_list *
1a10: 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75  /../*.** Make su
1a20: 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c 20 74  re we can call t
1a30: 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d 20 43  his stuff from C
1a40: 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65 78 74  ++..*/.#if 0.ext
1a50: 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66  ern "C" {.#endif
1a60: 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68 65  .../*.** Add the
1a70: 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72   ability to over
1a80: 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a 2f  ride 'extern'.*/
1a90: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
1aa0: 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65 20  EXTERN.# define 
1ab0: 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65 78  SQLITE_EXTERN ex
1ac0: 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 23 69 66  tern.#endif..#if
1ad0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a  ndef SQLITE_API.
1ae0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
1af0: 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  API.#endif.../*.
1b00: 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d  ** These no-op m
1b10: 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20 69  acros are used i
1b20: 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72  n front of inter
1b30: 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68  faces to mark th
1b40: 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ose.** interface
1b50: 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70 72  s as either depr
1b60: 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72 69  ecated or experi
1b70: 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70  mental.  New app
1b80: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
1b90: 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72  uld not use depr
1ba0: 65 63 61 74 65 64 20 69 6e 74 65 72 66 61 63 65  ecated interface
1bb0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70  s - they are sup
1bc0: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72  port for backwar
1bd0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
1be0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
1bf0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
1c00: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
1c10: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
1c20: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
1c30: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
1c40: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
1c50: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
1c60: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
1c70: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
1c80: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
1c90: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
1ca0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
1cb0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
1cc0: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
1cd0: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
1ce0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
1cf0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
1d00: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
1d10: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
1d20: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
1d30: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
1d40: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
1d50: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
1d60: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
1d70: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
1d80: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
1d90: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
1da0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
1db0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
1dc0: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
1dd0: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
1de0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
1df0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
1e00: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
1e10: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
1e20: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
1e30: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
1e40: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
1e50: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
1e60: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
1e70: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
1e80: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
1e90: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1ea0: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
1eb0: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
1ec0: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
1ed0: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
1ee0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
1ef0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
1f00: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
1f10: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
1f20: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1f30: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
1f40: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
1f50: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
1f60: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
1f70: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
1f80: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
1f90: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
1fa0: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
1fb0: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
1fc0: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
1fd0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
1fe0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
1ff0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
2000: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
2010: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
2020: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
2030: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
2040: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
2050: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
2060: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
2070: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
2080: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
2090: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
20a0: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
20b0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
20c0: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
20d0: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
20e0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
20f0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
2100: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
2110: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
2120: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
2130: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
2140: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
2150: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
2160: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
2170: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
2180: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
2190: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
21a0: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
21b0: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
21c0: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
21d0: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
21e0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
21f0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
2200: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
2210: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
2220: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
2230: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
2240: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
2250: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
2260: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
2270: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
2280: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
2290: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
22a0: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
22b0: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
22c0: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
22d0: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
22e0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
22f0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
2300: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
2310: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
2320: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
2330: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
2340: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
2350: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
2360: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
2370: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
2380: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
2390: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
23a0: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
23b0: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
23c0: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
23d0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
23e0: 20 20 20 20 20 22 33 2e 38 2e 34 2e 31 22 0a 23       "3.8.4.1".#
23f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
2400: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30  RSION_NUMBER 300
2410: 38 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  8004.#define SQL
2420: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20  ITE_SOURCE_ID   
2430: 20 20 20 22 32 30 31 34 2d 30 33 2d 31 31 20 31     "2014-03-11 1
2440: 35 3a 32 37 3a 33 36 20 30 31 38 64 33 31 37 62  5:27:36 018d317b
2450: 31 32 35 37 63 65 36 38 61 39 32 39 30 38 62 30  1257ce68a92908b0
2460: 35 63 39 63 37 63 66 31 34 39 34 30 35 30 64 30  5c9c7cf1494050d0
2470: 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  "../*.** CAPI3RE
2480: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
2490: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
24a0: 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ers.** KEYWORDS:
24b0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
24c0: 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  , sqlite3_source
24d0: 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  id.**.** These i
24e0: 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64  nterfaces provid
24f0: 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  e the same infor
2500: 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53  mation as the [S
2510: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a  QLITE_VERSION],.
2520: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
2530: 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20  ON_NUMBER], and 
2540: 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49  [SQLITE_SOURCE_I
2550: 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  D] C preprocesso
2560: 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20  r macros.** but 
2570: 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  are associated w
2580: 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20  ith the library 
2590: 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68  instead of the h
25a0: 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43  eader file.  ^(C
25b0: 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72  autious.** progr
25c0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63  ammers might inc
25d0: 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74  lude assert() st
25e0: 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69  atements in thei
25f0: 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  r application to
2600: 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20  .** verify that 
2610: 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2620: 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  by these interfa
2630: 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61  ces match the ma
2640: 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68  cros in.** the h
2650: 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20  eader, and thus 
2660: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
2670: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a  application is.*
2680: 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
2690: 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79  matching library
26a0: 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65   and header file
26b0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s..**.** <blockq
26c0: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73  uote><pre>.** as
26d0: 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69  sert( sqlite3_li
26e0: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
26f0: 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  )==SQLITE_VERSIO
2700: 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61  N_NUMBER );.** a
2710: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71  ssert( strcmp(sq
2720: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
2730: 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49  ,SQLITE_SOURCE_I
2740: 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65  D)==0 );.** asse
2750: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74  rt( strcmp(sqlit
2760: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c  e3_libversion(),
2770: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d  SQLITE_VERSION)=
2780: 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  =0 );.** </pre><
2790: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
27a0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
27b0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
27c0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74  ng constant cont
27d0: 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66  ains the text of
27e0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
27f0: 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68  ].** macro.  ^Th
2800: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
2810: 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20  sion() function 
2820: 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2830: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74  r to the.** to t
2840: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
2850: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
2860: 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74  tant.  The sqlit
2870: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a  e3_libversion().
2880: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ** function is p
2890: 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20  rovided for use 
28a0: 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c  in DLLs since DL
28b0: 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20  L users usually 
28c0: 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64  do not have.** d
28d0: 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20  irect access to 
28e0: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  string constants
28f0: 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e   within the DLL.
2900: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
2910: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
2920: 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ber() function r
2930: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
2940: 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53  r equal to.** [S
2950: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
2960: 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c  MBER].  ^The sql
2970: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
2980: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
2990: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
29a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
29b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
29c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
29d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
29e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
29f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a  rocessor macro..
2a00: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2a10: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
2a20: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
2a30: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
2a40: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2a50: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
2a60: 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54 45  rsion[] = SQLITE
2a70: 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54 45  _VERSION;.SQLITE
2a80: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2a90: 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  *sqlite3_libvers
2aa0: 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ion(void);.SQLIT
2ab0: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2ac0: 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65   *sqlite3_source
2ad0: 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  id(void);.SQLITE
2ae0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2af0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
2b00: 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  er(void);../*.**
2b10: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
2b20: 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70  ime Library Comp
2b30: 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20  ilation Options 
2b40: 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a  Diagnostics.**.*
2b50: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2b60: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
2b70: 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  d() function ret
2b80: 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20  urns 0 or 1 .** 
2b90: 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74 68  indicating wheth
2ba0: 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65 64  er the specified
2bb0: 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69   option was defi
2bc0: 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69  ned at .** compi
2bd0: 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53  le time.  ^The S
2be0: 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61  QLITE_ prefix ma
2bf0: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f  y be omitted fro
2c00: 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e  m the .** option
2c10: 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20   name passed to 
2c20: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
2c30: 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a  ption_used().  .
2c40: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c50: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
2c60: 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  _get() function 
2c70: 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67  allows iterating
2c80: 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73  .** over the lis
2c90: 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61  t of options tha
2ca0: 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20 61  t were defined a
2cb0: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62  t compile time b
2cc0: 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74  y.** returning t
2cd0: 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20  he N-th compile 
2ce0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69  time option stri
2cf0: 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75  ng.  ^If N is ou
2d00: 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73  t of range,.** s
2d10: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
2d20: 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72  tion_get() retur
2d30: 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
2d40: 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  r.  ^The SQLITE_
2d50: 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f   .** prefix is o
2d60: 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20  mitted from any 
2d70: 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
2d80: 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
2d90: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
2da0: 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70  t()..**.** ^Supp
2db0: 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61 67  ort for the diag
2dc0: 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73  nostic functions
2dd0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
2de0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a  option_used().**
2df0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d   and sqlite3_com
2e00: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
2e10: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20   may be omitted 
2e20: 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74 68  by specifying th
2e30: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d  e .** [SQLITE_OM
2e40: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e  IT_COMPILEOPTION
2e50: 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61  _DIAGS] option a
2e60: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a  t compile time..
2e70: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2e80: 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73  SQL functions [s
2e90: 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74  qlite_compileopt
2ea0: 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ion_used()] and.
2eb0: 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ** [sqlite_compi
2ec0: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20  leoption_get()] 
2ed0: 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65  and the [compile
2ee0: 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d  _options pragma]
2ef0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
2f00: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
2f10: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51 4c  OPTION_DIAGS.SQL
2f20: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2f30: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
2f40: 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61  n_used(const cha
2f50: 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53 51  r *zOptName);.SQ
2f60: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2f70: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
2f80: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
2f90: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
2fa0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
2fb0: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
2fc0: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
2fd0: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
2fe0: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
2ff0: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
3000: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
3010: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
3020: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
3030: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
3040: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
3050: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
3060: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
3070: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
3080: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
3090: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
30a0: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
30b0: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
30c0: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
30d0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
30e0: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
30f0: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
3100: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
3110: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
3120: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
3130: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
3140: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
3150: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
3160: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
3170: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
3180: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
3190: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
31a0: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
31b0: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
31c0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
31d0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
31e0: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
31f0: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
3200: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
3210: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
3220: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
3230: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
3240: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
3250: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
3260: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
3270: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
3280: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
3290: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
32a0: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
32b0: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
32c0: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
32d0: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
32e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
32f0: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
3300: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
3310: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
3320: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
3330: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
3340: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
3350: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
3360: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
3370: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
3380: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
3390: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
33a0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
33b0: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
33c0: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
33d0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
33e0: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
33f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
3400: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
3410: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
3420: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
3430: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
3440: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
3450: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
3460: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
3470: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
3480: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
3490: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
34a0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
34b0: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
34c0: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
34d0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
34e0: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
34f0: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
3500: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
3510: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
3520: 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20  .  ^(The return 
3530: 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20  value of the.** 
3540: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
3550: 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68  fe() function sh
3560: 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d  ows only the com
3570: 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e  pile-time settin
3580: 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73  g of.** thread s
3590: 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72  afety, not any r
35a0: 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20  un-time changes 
35b0: 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 20  to that setting 
35c0: 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74  made by.** sqlit
35d0: 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20  e3_config(). In 
35e0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
35f0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
3600: 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  om sqlite3_threa
3610: 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e  dsafe().** is un
3620: 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73  changed by calls
3630: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
3640: 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  ig().)^.**.** Se
3650: 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
3660: 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61   mode] documenta
3670: 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
3680: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
3690: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
36a0: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
36b0: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
36c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
36d0: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
36e0: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
36f0: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
3700: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
3710: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3720: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
3730: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
3740: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
3750: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
3760: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
3770: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
3780: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
3790: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
37a0: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
37b0: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
37c0: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
37d0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
37e0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
37f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
3800: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
3810: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
3820: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
3830: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
3840: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
3850: 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  e()].** and [sql
3860: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d  ite3_close_v2()]
3870: 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75 63   are its destruc
3880: 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72 65  tors.  There are
3890: 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69   many other.** i
38a0: 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20  nterfaces (such 
38b0: 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  as.** [sqlite3_p
38c0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
38d0: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
38e0: 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a  nction()], and.*
38f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  * [sqlite3_busy_
3900: 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61  timeout()] to na
3910: 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68  me but three) th
3920: 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f  at are methods o
3930: 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20  n an.** sqlite3 
3940: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64  object..*/.typed
3950: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
3960: 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a  3 sqlite3;../*.*
3970: 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42  * CAPI3REF: 64-B
3980: 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73  it Integer Types
3990: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
39a0: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74  lite_int64 sqlit
39b0: 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42  e_uint64.**.** B
39c0: 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20  ecause there is 
39d0: 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72  no cross-platfor
39e0: 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79  m way to specify
39f0: 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
3a00: 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20  types.** SQLite 
3a10: 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66  includes typedef
3a20: 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67  s for 64-bit sig
3a30: 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64  ned and unsigned
3a40: 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a   integers..**.**
3a50: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   The sqlite3_int
3a60: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75  64 and sqlite3_u
3a70: 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72  int64 are the pr
3a80: 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66  eferred type def
3a90: 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65  initions..** The
3aa0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e   sqlite_int64 an
3ab0: 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20  d sqlite_uint64 
3ac0: 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72  types are suppor
3ad0: 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ted for backward
3ae0: 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  s.** compatibili
3af0: 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ty only..**.** ^
3b00: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
3b10: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74  4 and sqlite_int
3b20: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
3b30: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
3b40: 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32  s.** between -92
3b50: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
3b60: 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33  8 and +922337203
3b70: 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75  6854775807 inclu
3b80: 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  sive.  ^The.** s
3b90: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e  qlite3_uint64 an
3ba0: 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20  d sqlite_uint64 
3bb0: 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20  types can store 
3bc0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a  integer values .
3bd0: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
3be0: 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30 39   +18446744073709
3bf0: 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65  551615 inclusive
3c00: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
3c10: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  TE_INT64_TYPE.  
3c20: 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49  typedef SQLITE_I
3c30: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
3c40: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
3c50: 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54  f unsigned SQLIT
3c60: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
3c70: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69  ite_uint64;.#eli
3c80: 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56  f defined(_MSC_V
3c90: 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f  ER) || defined(_
3ca0: 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74  _BORLANDC__).  t
3cb0: 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73  ypedef __int64 s
3cc0: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
3cd0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
3ce0: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  __int64 sqlite_u
3cf0: 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74  int64;.#else.  t
3d00: 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67  ypedef long long
3d10: 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36   int sqlite_int6
3d20: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
3d30: 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20  igned long long 
3d40: 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  int sqlite_uint6
3d50: 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65  4;.#endif.typede
3d60: 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  f sqlite_int64 s
3d70: 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79  qlite3_int64;.ty
3d80: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e  pedef sqlite_uin
3d90: 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  t64 sqlite3_uint
3da0: 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f  64;../*.** If co
3db0: 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72  mpiling for a pr
3dc0: 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63  ocessor that lac
3dd0: 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  ks floating poin
3de0: 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75  t support,.** su
3df0: 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72  bstitute integer
3e00: 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f   for floating-po
3e10: 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  int..*/.#ifdef S
3e20: 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54  QLITE_OMIT_FLOAT
3e30: 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69  ING_POINT.# defi
3e40: 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  ne double sqlite
3e50: 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a  3_int64.#endif..
3e60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3e70: 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61  Closing A Databa
3e80: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
3e90: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3ea0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
3eb0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3ec0: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
3ed0: 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20  tructors.** for 
3ee0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
3ef0: 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20  ject..** ^Calls 
3f00: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  to sqlite3_close
3f10: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
3f20: 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e  lose_v2() return
3f30: 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 0a 2a 2a   SQLITE_OK if.**
3f40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
3f50: 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73  bject is success
3f60: 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20  fully destroyed 
3f70: 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74  and all associat
3f80: 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ed.** resources 
3f90: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
3fa0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  .**.** ^If the d
3fb0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3fc0: 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  on is associated
3fd0: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
3fe0: 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  d prepared.** st
3ff0: 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69  atements or unfi
4000: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
4010: 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68  ackup objects th
4020: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  en sqlite3_close
4030: 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65  ().** will leave
4040: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
4050: 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e  nnection open an
4060: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
4070: 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73  _BUSY]..** ^If s
4080: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
4090: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
40a0: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
40b0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
40c0: 0a 2a 2a 20 61 6e 64 20 75 6e 66 69 6e 69 73 68  .** and unfinish
40d0: 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  ed sqlite3_backu
40e0: 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ps, then the dat
40f0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4100: 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75   becomes.** an u
4110: 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22  nusable "zombie"
4120: 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f   which will auto
4130: 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61  matically be dea
4140: 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68  llocated when th
4150: 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72  e.** last prepar
4160: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
4170: 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65  finalized or the
4180: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61   last sqlite3_ba
4190: 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73  ckup is.** finis
41a0: 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65  hed.  The sqlite
41b0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74  3_close_v2() int
41c0: 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64  erface is intend
41d0: 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a  ed for use with.
41e0: 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65  ** host language
41f0: 73 20 74 68 61 74 20 61 72 65 20 67 61 72 62 61  s that are garba
4200: 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e  ge collected, an
4210: 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 64 65  d where the orde
4220: 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65  r in which.** de
4230: 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 63 61  structors are ca
4240: 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 61 72  lled is arbitrar
4250: 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  y..**.** Applica
4260: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71  tions should [sq
4270: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
4280: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b   finalize] all [
4290: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
42a0: 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  nts],.** [sqlite
42b0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
42c0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
42d0: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a  handles], and .*
42e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
42f0: 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73  p_finish | finis
4300: 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  h] all [sqlite3_
4310: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
4320: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
4330: 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  th the [sqlite3]
4340: 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f   object prior to
4350: 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63   attempting to c
4360: 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e  lose the object.
4370: 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33    ^If.** sqlite3
4380: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63  _close_v2() is c
4390: 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61  alled on a [data
43a0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
43b0: 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a   that still has.
43c0: 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b  ** outstanding [
43d0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
43e0: 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64  nts], [BLOB hand
43f0: 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  les], and/or.** 
4400: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
4410: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74   objects then it
4420: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
4430: 4f 4b 20 62 75 74 20 74 68 65 20 64 65 61 6c 6c  OK but the deall
4440: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
4450: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
4460: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
4470: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
4480: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
4490: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
44a0: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
44b0: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
44c0: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
44d0: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
44e0: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
44f0: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
4500: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
4510: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
4520: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
4530: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
4540: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
4550: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
4560: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
4570: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
4580: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
4590: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
45a0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
45b0: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
45c0: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
45d0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
45e0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
45f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
4600: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
4610: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
4620: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
4630: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
4640: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
4650: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
4660: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
4670: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
4680: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
4690: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
46a0: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
46b0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73   sqlite3_close(s
46c0: 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45  qlite3*);.SQLITE
46d0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
46e0: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
46f0: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
4700: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
4710: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
4720: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
4730: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
4740: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
4750: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
4760: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
4770: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
4780: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
4790: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
47a0: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
47b0: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
47c0: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
47d0: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
47e0: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
47f0: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
4800: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
4810: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
4820: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
4830: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
4840: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
4850: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
4860: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
4870: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
4880: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
4890: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
48a0: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
48b0: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
48c0: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
48d0: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
48e0: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
48f0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
4900: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
4910: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
4920: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
4930: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
4940: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
4950: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
4960: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
4970: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
4980: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
4990: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
49a0: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
49b0: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
49c0: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
49d0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
49e0: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
49f0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
4a00: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
4a10: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
4a20: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
4a30: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
4a40: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
4a50: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
4a60: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
4a70: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
4a80: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
4a90: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
4aa0: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
4ab0: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
4ac0: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
4ad0: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
4ae0: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
4af0: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
4b00: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
4b10: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
4b20: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
4b30: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
4b40: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
4b50: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
4b60: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
4b70: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
4b80: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
4b90: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
4ba0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
4bb0: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
4bc0: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
4bd0: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
4be0: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
4bf0: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
4c00: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
4c10: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
4c20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
4c30: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
4c40: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
4c50: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
4c60: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
4c70: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
4c80: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
4c90: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
4ca0: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
4cb0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
4cc0: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
4cd0: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
4ce0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
4cf0: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
4d00: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
4d10: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
4d20: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
4d30: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
4d40: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
4d50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4d60: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
4d70: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
4d80: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
4d90: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
4da0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
4db0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
4dc0: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
4dd0: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
4de0: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
4df0: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
4e00: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
4e10: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
4e20: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
4e30: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
4e40: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
4e50: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
4e60: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
4e70: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
4e80: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
4e90: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
4ea0: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
4eb0: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
4ec0: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
4ed0: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
4ee0: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
4ef0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
4f00: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
4f10: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
4f20: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
4f30: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
4f40: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
4f50: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
4f60: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
4f70: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
4f80: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
4f90: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
4fa0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
4fb0: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
4fc0: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
4fd0: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
4fe0: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
4ff0: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
5000: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
5010: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
5020: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
5030: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
5040: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
5050: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
5060: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
5070: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
5080: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
5090: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
50a0: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
50b0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
50c0: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
50d0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
50e0: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
50f0: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
5100: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
5110: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
5120: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
5130: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
5140: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
5150: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
5160: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
5170: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
5180: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
5190: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
51a0: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
51b0: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
51c0: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
51d0: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
51e0: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
51f0: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
5200: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
5210: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
5220: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
5230: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
5240: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
5250: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
5260: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
5270: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
5280: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
5290: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
52a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
52b0: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
52c0: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
52d0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
52e0: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
52f0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
5300: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
5310: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
5320: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
5330: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
5340: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
5350: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
5360: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
5370: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
5380: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
5390: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
53a0: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
53b0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
53c0: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
53d0: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
53e0: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
53f0: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
5400: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
5410: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
5420: 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l>.*/.SQLITE_API
5430: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65   int sqlite3_exe
5440: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  c(.  sqlite3*,  
5450: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5460: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5470: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
5480: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
5490: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20  har *sql,       
54a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
54b0: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
54c0: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
54d0: 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28  int (*callback)(
54e0: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
54f0: 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61  ,char**),  /* Ca
5500: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
5510: 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20  */.  void *,    
5520: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5530: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5540: 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20  /* 1st argument 
5550: 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20  to callback */. 
5560: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20   char **errmsg  
5570: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5580: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
5590: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
55a0: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   here */.);../*.
55b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
55c0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
55d0: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b  WORDS: SQLITE_OK
55e0: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65   {error code} {e
55f0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
5600: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
5610: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63   code} {result c
5620: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  odes}.**.** Many
5630: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e   SQLite function
5640: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65  s return an inte
5650: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ger result code 
5660: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f  from the set sho
5670: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72  wn.** here in or
5680: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20  der to indicate 
5690: 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75  success or failu
56a0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72  re..**.** New er
56b0: 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65  ror codes may be
56c0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
56d0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
56e0: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ite..**.** See a
56f0: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  lso: [SQLITE_IOE
5700: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
5710: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
5720: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74  ,.** [sqlite3_vt
5730: 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
5740: 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41  ] [SQLITE_ROLLBA
5750: 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  CK | result code
5760: 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s]..*/.#define S
5770: 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20  QLITE_OK        
5780: 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73     0   /* Succes
5790: 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f  sful result */./
57a0: 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65  * beginning-of-e
57b0: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64  rror-codes */.#d
57c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
57d0: 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a  OR        1   /*
57e0: 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69   SQL error or mi
57f0: 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a  ssing database *
5800: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5810: 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20  _INTERNAL     2 
5820: 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f    /* Internal lo
5830: 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c  gic error in SQL
5840: 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ite */.#define S
5850: 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20  QLITE_PERM      
5860: 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73     3   /* Access
5870: 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69   permission deni
5880: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
5890: 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20  LITE_ABORT      
58a0: 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63    4   /* Callbac
58b0: 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73  k routine reques
58c0: 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a  ted an abort */.
58d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
58e0: 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20  USY         5   
58f0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
5900: 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  file is locked *
5910: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5920: 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20  _LOCKED       6 
5930: 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20    /* A table in 
5940: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
5950: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
5960: 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20  e SQLITE_NOMEM  
5970: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d        7   /* A m
5980: 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a  alloc() failed *
5990: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
59a0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20  _READONLY     8 
59b0: 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20    /* Attempt to 
59c0: 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79  write a readonly
59d0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
59f0: 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20  RRUPT    9   /* 
5a00: 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e  Operation termin
5a10: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
5a20: 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64  interrupt()*/.#d
5a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5a40: 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a  RR       10   /*
5a50: 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69   Some kind of di
5a60: 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63  sk I/O error occ
5a70: 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  urred */.#define
5a80: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20   SQLITE_CORRUPT 
5a90: 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20      11   /* The 
5aa0: 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d  database disk im
5ab0: 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64  age is malformed
5ac0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5ad0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31  TE_NOTFOUND    1
5ae0: 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f  2   /* Unknown o
5af0: 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33  pcode in sqlite3
5b00: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20  _file_control() 
5b10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b20: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33  E_FULL        13
5b30: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20     /* Insertion 
5b40: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64  failed because d
5b50: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20  atabase is full 
5b60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b70: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34  E_CANTOPEN    14
5b80: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20     /* Unable to 
5b90: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
5ba0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
5bb0: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f  e SQLITE_PROTOCO
5bc0: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74  L    15   /* Dat
5bd0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
5be0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
5bf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
5c00: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
5c10: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
5c20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5c30: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
5c40: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
5c50: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
5c60: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
5c70: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
5c80: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
5c90: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
5ca0: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
5cb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5cc0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
5cd0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
5ce0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
5cf0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
5d00: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
5d10: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
5d20: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
5d30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
5d40: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
5d50: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
5d60: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
5d70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
5d80: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
5d90: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
5da0: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
5db0: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
5dc0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
5dd0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
5de0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
5df0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
5e00: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
5e10: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
5e20: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
5e30: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
5e40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
5e50: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
5e60: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
5e70: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
5e80: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
5e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5ea0: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
5eb0: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
5ec0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
5ed0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
5ee0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5ef0: 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e  E      27   /* N
5f00: 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f  otifications fro
5f10: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
5f20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f30: 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38  E_WARNING     28
5f40: 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66     /* Warnings f
5f50: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
5f60: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5f70: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
5f80: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
5f90: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
5fa0: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
5fb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
5fc0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
5fd0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
5fe0: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
5ff0: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
6000: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
6010: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
6020: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
6030: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
6040: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
6050: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  ed error code} {
6060: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
6070: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
6080: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73  S: {extended res
6090: 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e  ult code} {exten
60a0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
60b0: 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64  }.**.** In its d
60c0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
60d0: 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49  tion, SQLite API
60e0: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
60f0: 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67   one of 26 integ
6100: 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  er.** [SQLITE_OK
6110: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
6120: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
6130: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
6140: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
6150: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
6160: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
6170: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
6180: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
6190: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
61a0: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
61b0: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
61c0: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
61d0: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
61e0: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
61f0: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
6200: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
6210: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
6220: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
6230: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
6240: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
6250: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
6260: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
6270: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
6280: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
6290: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
62a0: 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62  t codes are enab
62b0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
62c0: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
62d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
62e0: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
62f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
6300: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
6310: 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20  s()] API..**.** 
6320: 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69  Some of the avai
6330: 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72  lable extended r
6340: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
6350: 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20  listed here..** 
6360: 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 74  One may expect t
6370: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
6380: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
6390: 65 73 20 77 69 6c 6c 20 69 6e 63 72 65 61 73 65  es will increase
63a0: 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20  .** over time.  
63b0: 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 75 73  Software that us
63c0: 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  es extended resu
63d0: 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20  lt codes should 
63e0: 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65  expect.** to see
63f0: 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65   new result code
6400: 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  s in future rele
6410: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
6420: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
6430: 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20  _OK result code 
6440: 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78  will never be ex
6450: 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c  tended.  It will
6460: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78   always.** be ex
6470: 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23  actly zero..*/.#
6480: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6490: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20  ERR_READ        
64a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
64b0: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
64c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
64d0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
64e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
64f0: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
6500: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
6510: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
6520: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
6530: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
6540: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
6550: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  _FSYNC          
6560: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
6570: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
6580: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
6590: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  DIR_FSYNC       
65a0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
65b0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
65c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
65d0: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20  RUNCATE         
65e0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
65f0: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
6600: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
6610: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20  TAT             
6620: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
6630: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
6640: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
6650: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
6660: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
6670: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
6680: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f  QLITE_IOERR_RDLO
6690: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
66a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
66b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
66c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
66d0: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  E            (SQ
66e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
66f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6700: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
6710: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ED           (SQ
6720: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
6730: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6740: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d  LITE_IOERR_NOMEM
6750: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
6760: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32  LITE_IOERR | (12
6770: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6780: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53  LITE_IOERR_ACCES
6790: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  S            (SQ
67a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33  LITE_IOERR | (13
67b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
67c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b  LITE_IOERR_CHECK
67d0: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51  RESERVEDLOCK (SQ
67e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34  LITE_IOERR | (14
67f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6800: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20  LITE_IOERR_LOCK 
6810: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
6820: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35  LITE_IOERR | (15
6830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6840: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45  LITE_IOERR_CLOSE
6850: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
6860: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36  LITE_IOERR | (16
6870: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6880: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43  LITE_IOERR_DIR_C
6890: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51  LOSE         (SQ
68a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37  LITE_IOERR | (17
68b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
68c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50  LITE_IOERR_SHMOP
68d0: 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51  EN           (SQ
68e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38  LITE_IOERR | (18
68f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6900: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49  LITE_IOERR_SHMSI
6910: 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ZE           (SQ
6920: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39  LITE_IOERR | (19
6930: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6940: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f  LITE_IOERR_SHMLO
6950: 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51  CK           (SQ
6960: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30  LITE_IOERR | (20
6970: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6980: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41  LITE_IOERR_SHMMA
6990: 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  P            (SQ
69a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31  LITE_IOERR | (21
69b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
69c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20  LITE_IOERR_SEEK 
69d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
69e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32  LITE_IOERR | (22
69f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6a00: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
6a10: 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51  E_NOENT      (SQ
6a20: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33  LITE_IOERR | (23
6a30: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6a40: 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20  LITE_IOERR_MMAP 
6a50: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
6a60: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34  LITE_IOERR | (24
6a70: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6a80: 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45  LITE_IOERR_GETTE
6a90: 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51  MPPATH       (SQ
6aa0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35  LITE_IOERR | (25
6ab0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6ac0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50  LITE_IOERR_CONVP
6ad0: 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51  ATH          (SQ
6ae0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36  LITE_IOERR | (26
6af0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6b00: 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52  LITE_LOCKED_SHAR
6b10: 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51  EDCACHE      (SQ
6b20: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28  LITE_LOCKED |  (
6b30: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
6b40: 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56  QLITE_BUSY_RECOV
6b50: 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53  ERY           (S
6b60: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
6b70: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
6b80: 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50  SQLITE_BUSY_SNAP
6b90: 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28  SHOT           (
6ba0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
6bb0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
6bc0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
6bd0: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20  _NOTEMPDIR      
6be0: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
6bf0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
6c00: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
6c10: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20  EN_ISDIR        
6c20: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
6c30: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  EN | (2<<8)).#de
6c40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
6c50: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20  OPEN_FULLPATH   
6c60: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
6c70: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OPEN | (3<<8)).#
6c80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
6c90: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20  NTOPEN_CONVPATH 
6ca0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
6cb0: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29  NTOPEN | (4<<8))
6cc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6cd0: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
6ce0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
6cf0: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
6d00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6d10: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
6d20: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
6d30: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
6d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
6d50: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
6d60: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
6d70: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
6d80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6d90: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
6da0: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
6db0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
6dc0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
6dd0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
6de0: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28  DBMOVED        (
6df0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
6e00: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
6e10: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
6e20: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
6e30: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
6e40: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
6e50: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6e60: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
6e70: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6e80: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
6e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
6ea0: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
6eb0: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
6ec0: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
6ed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ee0: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
6ef0: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
6f00: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
6f10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
6f20: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
6f30: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
6f40: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
6f50: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
6f60: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6f70: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
6f80: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6f90: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
6fa0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
6fb0: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
6fc0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
6fd0: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
6fe0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ff0: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
7000: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
7010: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
7020: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7030: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
7040: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
7050: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
7060: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
7070: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
7080: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
7090: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
70a0: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
70b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
70c0: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20  TRAINT_ROWID    
70d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
70e0: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29  TRAINT |(10<<8))
70f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7100: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57  NOTICE_RECOVER_W
7110: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  AL      (SQLITE_
7120: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29  NOTICE | (1<<8))
7130: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7140: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52  NOTICE_RECOVER_R
7150: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f  OLLBACK (SQLITE_
7160: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29  NOTICE | (2<<8))
7170: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7180: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45  WARNING_AUTOINDE
7190: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  X       (SQLITE_
71a0: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29  WARNING | (1<<8)
71b0: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
71c0: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
71d0: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
71e0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
71f0: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
7200: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
7210: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
7220: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
7230: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
7240: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
7250: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
7260: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
7270: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7280: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
7290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
72a0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
72b0: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
72c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
72d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
72e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
72f0: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
7300: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
7310: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
7320: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
7330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
7340: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
7350: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
7360: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
7370: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
7380: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
7390: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
73a0: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
73b0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
73c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
73d0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
73e0: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
73f0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
7400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
7410: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
7420: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
7430: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
7440: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
7450: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
7460: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
7470: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
7480: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
7490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
74a0: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
74b0: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
74c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
74d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
74e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
74f0: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
7500: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
7510: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
7520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
7530: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
7540: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
7550: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
7560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
7570: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
7580: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
7590: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
75a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
75b0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
75c0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
75d0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
75e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
75f0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
7600: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
7610: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
7620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
7630: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
7640: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
7650: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
7660: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
7670: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
7680: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
7690: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
76a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
76b0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
76c0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
76d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
76e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
76f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
7700: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
7710: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
7720: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
7730: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
7740: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
7750: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
7760: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
7770: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
7780: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
7790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
77a0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
77b0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
77c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
77d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
77e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
77f0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
7800: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
7810: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
7820: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
7830: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
7840: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
7850: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7860: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
7870: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
7880: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
7890: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
78a0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
78b0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
78c0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
78d0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
78e0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
78f0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
7900: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
7910: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
7920: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
7930: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
7940: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
7950: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
7960: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7970: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
7980: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
7990: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
79a0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
79b0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
79c0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
79d0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
79e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
79f0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
7a00: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
7a10: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
7a20: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
7a30: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
7a40: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
7a50: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
7a60: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
7a70: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
7a80: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
7a90: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
7aa0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
7ab0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
7ac0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
7ad0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
7ae0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
7af0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
7b00: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
7b10: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
7b20: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
7b30: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
7b40: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7b50: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
7b60: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
7b70: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
7b80: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
7b90: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
7ba0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
7bb0: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68  to xWrite().  Th
7bc0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
7bd0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
7be0: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  TE property mean
7bf0: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20  s that.** after 
7c00: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67  reboot following
7c10: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65   a crash or powe
7c20: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79  r loss, the only
7c30: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66   bytes in a.** f
7c40: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72  ile that were wr
7c50: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70  itten at the app
7c60: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d  lication level m
7c70: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65  ight have change
7c80: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64  d.** and that ad
7c90: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76  jacent bytes, ev
7ca0: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20  en bytes within 
7cb0: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20  the same sector 
7cc0: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  are.** guarantee
7cd0: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65  d to be unchange
7ce0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
7cf0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
7d00: 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c  _WHEN_OPEN.** fl
7d10: 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  ag indicate that
7d20: 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62   a file cannot b
7d30: 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f  e deleted when o
7d40: 70 65 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  pen..*/.#define 
7d50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7d60: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
7d70: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
7d80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7d90: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
7da0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7db0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
7dc0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7dd0: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
7de0: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
7df0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7e00: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
7e10: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
7e20: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
7e30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
7e40: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
7e50: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
7e60: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7e70: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
7e80: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
7e90: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7ea0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
7eb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
7ec0: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
7ed0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7ee0: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
7ef0: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
7f00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7f10: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
7f20: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7f30: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
7f40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
7f50: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
7f60: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
7f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7f80: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
7f90: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7fa0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
7fb0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
7fc0: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
7fd0: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
7fe0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7ff0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
8000: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
8010: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
8020: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67  EF: File Locking
8030: 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51   Levels.**.** SQ
8040: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
8050: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
8060: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
8070: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
8080: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
8090: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
80a0: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
80b0: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
80c0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
80d0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
80e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
80f0: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
8100: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
8110: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
8120: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
8130: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8140: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
8150: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
8160: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
8170: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
8180: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
8190: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
81a0: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
81b0: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a  tion Type Flags.
81c0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74  **.** When SQLit
81d0: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
81e0: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  ync() method of 
81f0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
8200: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
8210: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62  t it uses a comb
8220: 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68  ination of.** th
8230: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
8240: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
8250: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
8260: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   When the SQLITE
8270: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66  _SYNC_DATAONLY f
8280: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20  lag is used, it 
8290: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a  means that the.*
82a0: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  * sync operation
82b0: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66   only needs to f
82c0: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73  lush data to mas
82d0: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64  s storage.  Inod
82e0: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
82f0: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75   need not be flu
8300: 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77  shed. If the low
8310: 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20  er four bits of 
8320: 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61  the flag.** equa
8330: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  l SQLITE_SYNC_NO
8340: 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  RMAL, that means
8350: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66   to use normal f
8360: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73  sync() semantics
8370: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65  ..** If the lowe
8380: 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61  r four bits equa
8390: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  l SQLITE_SYNC_FU
83a0: 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  LL, that means.*
83b0: 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20  * to use Mac OS 
83c0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
83d0: 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e   instead of fsyn
83e0: 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f  c()..**.** Do no
83f0: 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51  t confuse the SQ
8400: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
8410: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
8420: 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77  _FULL flags.** w
8430: 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20  ith the [PRAGMA 
8440: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52  synchronous]=NOR
8450: 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  MAL and [PRAGMA 
8460: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c  synchronous]=FUL
8470: 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20  L.** settings.  
8480: 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73  The [synchronous
8490: 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69   pragma] determi
84a0: 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74  nes when calls t
84b0: 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56  o the.** xSync V
84c0: 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20  FS method occur 
84d0: 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66  and applies unif
84e0: 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c  ormly across all
84f0: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54   platforms..** T
8500: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
8510: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
8520: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
8530: 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a   determine how.*
8540: 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72  * energetic or r
8550: 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65  igorous or force
8560: 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65  ful the sync ope
8570: 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a  rations are and.
8580: 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64  ** only make a d
8590: 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63  ifference on Mac
85a0: 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66   OSX for the def
85b0: 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65  ault SQLite code
85c0: 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74  ..** (Third-part
85d0: 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  y VFS implementa
85e0: 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f  tions might also
85f0: 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
8600: 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e  ction.** between
8610: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
8620: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
8630: 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d  YNC_FULL, but am
8640: 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61  ong the.** opera
8650: 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74  ting systems nat
8660: 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20  ively supported 
8670: 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20  by SQLite, only 
8680: 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73  Mac OSX.** cares
8690: 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65   about the diffe
86a0: 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69  rence.).*/.#defi
86b0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  ne SQLITE_SYNC_N
86c0: 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30  ORMAL        0x0
86d0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
86e0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20  ITE_SYNC_FULL   
86f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23         0x00003.#
8700: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
8710: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20  NC_DATAONLY     
8720: 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20   0x00010../*.** 
8730: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
8740: 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65  erface Open File
8750: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e   Handle.**.** An
8760: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
8770: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
8780: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
8790: 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  n the .** [sqlit
87a0: 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65  e3_vfs | OS inte
87b0: 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49  rface layer].  I
87c0: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74  ndividual OS int
87d0: 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d  erface.** implem
87e0: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a  entations will.*
87f0: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61  * want to subcla
8800: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62  ss this object b
8810: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69  y appending addi
8820: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
8830: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75   for their own u
8840: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64  se.  The pMethod
8850: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69  s entry is a poi
8860: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
8870: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8880: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
8890: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66  efines methods f
88a0: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a  or performing.**
88b0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
88c0: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  on the open file
88d0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
88e0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
88f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73   sqlite3_file;.s
8900: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
8910: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72  le {.  const str
8920: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8930: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73  ethods *pMethods
8940: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f  ;  /* Methods fo
8950: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a  r an open file *
8960: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
8970: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
8980: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20  ce File Virtual 
8990: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a  Methods Object.*
89a0: 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20  *.** Every file 
89b0: 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73  opened by the [s
89c0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
89d0: 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74  ] method populat
89e0: 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  es an.** [sqlite
89f0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28  3_file] object (
8a00: 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c  or, more commonl
8a10: 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66  y, a subclass of
8a20: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
8a30: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77  _file] object) w
8a40: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ith a pointer to
8a50: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
8a60: 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  this object..** 
8a70: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  This object defi
8a80: 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20  nes the methods 
8a90: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20  used to perform 
8aa0: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f  various operatio
8ab0: 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68  ns.** against th
8ac0: 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72  e open file repr
8ad0: 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b  esented by the [
8ae0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
8af0: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ject..**.** If t
8b00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
8b10: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65  xOpen] method se
8b20: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  ts the sqlite3_f
8b30: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
8b40: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f  ment .** to a no
8b50: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
8b60: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
8b70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f  _io_methods.xClo
8b80: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79  se method.** may
8b90: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e   be invoked even
8ba0: 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   if the [sqlite3
8bb0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f  _vfs.xOpen] repo
8bc0: 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69  rted that it fai
8bd0: 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c  led.  The.** onl
8be0: 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74  y way to prevent
8bf0: 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73   a call to xClos
8c00: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  e following a fa
8c10: 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66  iled [sqlite3_vf
8c20: 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66  s.xOpen].** is f
8c30: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8c40: 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65  vfs.xOpen] to se
8c50: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
8c60: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
8c70: 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a  ent.** to NULL..
8c80: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
8c90: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e  argument to xSyn
8ca0: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  c may be one of 
8cb0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52  [SQLITE_SYNC_NOR
8cc0: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  MAL] or.** [SQLI
8cd0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20  TE_SYNC_FULL].  
8ce0: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65  The first choice
8cf0: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66   is the normal f
8d00: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73  sync()..** The s
8d10: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20  econd choice is 
8d20: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  a Mac OS X style
8d30: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20   fullsync.  The 
8d40: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54  [SQLITE_SYNC_DAT
8d50: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d  AONLY].** flag m
8d60: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f  ay be ORed in to
8d70: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
8d80: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
8d90: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20  the file.** and 
8da0: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65  not its inode ne
8db0: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64  eds to be synced
8dc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ..**.** The inte
8dd0: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
8de0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
8df0: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
8e00: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
8e10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
8e20: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
8e30: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
8e40: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8e50: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
8e60: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8e70: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
8e80: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
8e90: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
8ea0: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
8eb0: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
8ec0: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
8ed0: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
8ee0: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65  the lock..** The
8ef0: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
8f00: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65  ock() method che
8f10: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20  cks whether any 
8f20: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
8f30: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69  ion,.** either i
8f40: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f  n this process o
8f50: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
8f60: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
8f70: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a  ing a RESERVED,.
8f80: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
8f90: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
8fa0: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
8fb0: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
8fc0: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
8fd0: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f  ists and false o
8fe0: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
8ff0: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  The xFileControl
9000: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67  () method is a g
9010: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65  eneric interface
9020: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73   that allows cus
9030: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65  tom.** VFS imple
9040: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69  mentations to di
9050: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61  rectly control a
9060: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e  n open file usin
9070: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
9080: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9090: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  ] interface.  Th
90a0: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72  e second "op" ar
90b0: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20  gument is an.** 
90c0: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20  integer opcode. 
90d0: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
90e0: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
90f0: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65   pointer intende
9100: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  d to.** point to
9110: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
9120: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
9130: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
9140: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
9150: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
9160: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
9170: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
9180: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
9190: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
91a0: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
91b0: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
91c0: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
91d0: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
91e0: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
91f0: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
9200: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
9210: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
9220: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
9230: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
9240: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
9250: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
9260: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c  ore reserves all
9270: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
9280: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
9290: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51  wn use..** A [SQ
92a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
92b0: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
92c0: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
92d0: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
92e0: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
92f0: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
9300: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
9310: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
9320: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
9330: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
9340: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
9350: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70  flicts.  VFS imp
9360: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
9370: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
9380: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20  QLITE_NOTFOUND] 
9390: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  for file control
93a0: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68   opcodes that th
93b0: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63  ey do not.** rec
93c0: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ognize..**.** Th
93d0: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
93e0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
93f0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
9400: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
9410: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
9420: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
9430: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
9440: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
9450: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
9460: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
9470: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
9480: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
9490: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
94a0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
94b0: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
94c0: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
94d0: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
94e0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
94f0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
9500: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
9510: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
9520: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
9530: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
9540: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
9550: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
9560: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
9570: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
9580: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
9590: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
95a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
95b0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
95c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
95d0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
95e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
95f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
9600: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
9610: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
9620: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
9630: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
9640: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
9650: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
9660: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
9670: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
9680: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
9690: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
96a0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
96b0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
96c0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
96d0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
96e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
96f0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
9700: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
9710: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
9720: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
9730: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
9740: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
9750: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
9760: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
9770: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
9780: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
9790: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
97a0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
97b0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
97c0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
97d0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
97e0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
97f0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
9800: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
9810: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
9820: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
9830: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
9840: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
9850: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
9860: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
9870: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
9880: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
9890: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
98a0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
98b0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
98c0: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
98d0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
98e0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
98f0: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
9900: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
9910: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
9920: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
9930: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
9940: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
9950: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
9960: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
9970: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
9980: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
9990: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
99a0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
99b0: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
99c0: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
99d0: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
99e0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
99f0: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
9a00: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
9a10: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
9a20: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
9a30: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
9a40: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
9a50: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
9a60: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
9a70: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
9a80: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
9a90: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
9aa0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
9ab0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
9ac0: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
9ad0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
9ae0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
9af0: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
9b00: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
9b10: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
9b20: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
9b30: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
9b40: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
9b50: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
9b60: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
9b70: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
9b80: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
9b90: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
9ba0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
9bb0: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
9bc0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
9bd0: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
9be0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
9bf0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
9c00: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
9c10: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
9c20: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
9c30: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
9c40: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
9c50: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
9c60: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
9c70: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
9c80: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
9c90: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
9ca0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
9cb0: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
9cc0: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
9cd0: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
9ce0: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
9cf0: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
9d00: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
9d10: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
9d20: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
9d30: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
9d40: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
9d50: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
9d60: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
9d70: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
9d80: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
9d90: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
9da0: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
9db0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9dc0: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
9dd0: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
9de0: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
9df0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
9e00: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
9e10: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
9e20: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
9e30: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
9e40: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
9e50: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
9e60: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
9e70: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
9e80: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
9e90: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
9ea0: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
9eb0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
9ec0: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
9ed0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
9ee0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
9ef0: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a  rol Opcodes.**.*
9f00: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
9f10: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
9f20: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
9f30: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
9f40: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
9f50: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
9f60: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20   object and for 
9f70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9f80: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20  e_control()].** 
9f90: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
9fa0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9fb0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
9fc0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
9fd0: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
9fe0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
9ff0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
a000: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
a010: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
a020: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
a030: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
a040: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
a050: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
a060: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
a070: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
a080: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
a090: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
a0a0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
a0b0: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
a0c0: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
a0d0: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
a0e0: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
a0f0: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
a100: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
a110: 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  ing and only nee
a120: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
a130: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
a140: 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65  EST.** is define
a150: 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  d..** <ul>.** <l
a160: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a170: 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20  _SIZE_HINT]].** 
a180: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a190: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63  L_SIZE_HINT] opc
a1a0: 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53  ode is used by S
a1b0: 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68  QLite to give th
a1c0: 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61  e VFS.** layer a
a1d0: 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72   hint of how lar
a1e0: 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
a1f0: 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74  file will grow t
a200: 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a  o be during the.
a210: 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73  ** current trans
a220: 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69  action.  This hi
a230: 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e  nt is not guaran
a240: 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72  teed to be accur
a250: 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73  ate but it.** is
a260: 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54   often close.  T
a270: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46  he underlying VF
a280: 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74  S might choose t
a290: 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61  o preallocate da
a2a0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73  tabase.** file s
a2b0: 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68  pace based on th
a2c0: 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72  is hint in order
a2d0: 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20   to help writes 
a2e0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
a2f0: 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74  ** file run fast
a300: 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  er..**.** <li>[[
a310: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
a320: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  NK_SIZE]].** The
a330: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
a340: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64  HUNK_SIZE] opcod
a350: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71  e is used to req
a360: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46  uest that the VF
a370: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64  S.** extends and
a380: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64   truncates the d
a390: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20  atabase file in 
a3a0: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65  chunks of a size
a3b0: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
a3c0: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66   the user. The f
a3d0: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
a3e0: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  o [sqlite3_file_
a3f0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c  control()] shoul
a400: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  d .** point to a
a410: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20  n integer (type 
a420: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  int) containing 
a430: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69  the new chunk-si
a440: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72  ze to use.** for
a450: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64   the nominated d
a460: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74  atabase. Allocat
a470: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c  ing database fil
a480: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65  e space in large
a490: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20  .** chunks (say 
a4a0: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20  1MB at a time), 
a4b0: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d  may reduce file-
a4c0: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61  system fragmenta
a4d0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72  tion and.** impr
a4e0: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
a4f0: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
a500: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a510: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
a520: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
a530: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
a540: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  LE_POINTER] opco
a550: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
a560: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
a570: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
a580: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
a590: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
a5a0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
a5b0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
a5c0: 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71  on.  See the [sq
a5d0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a5e0: 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74  ol()] documentat
a5f0: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  ion for.** addit
a600: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
a610: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
a620: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
a630: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f  _OMITTED]].** No
a640: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a   longer in use..
a650: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a660: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a  TE_FCNTL_SYNC]].
a670: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
a680: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64  CNTL_SYNC] opcod
a690: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
a6a0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
a6b0: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20  ite and.** sent 
a6c0: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64  to the VFS immed
a6d0: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68  iately before th
a6e0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
a6f0: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a  s invoked on a.*
a700: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  * database file 
a710: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20  descriptor. Or, 
a720: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  if the xSync met
a730: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  hod is not invok
a740: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74  ed .** because t
a750: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66  he user has conf
a760: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69  igured SQLite wi
a770: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73  th .** [PRAGMA s
a780: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
a790: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
a7a0: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b  OFF] it is invok
a7b0: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20  ed in place .** 
a7c0: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  of the xSync met
a7d0: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73  hod. In most cas
a7e0: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20  es, the pointer 
a7f0: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
a800: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c  with.** this fil
a810: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c  e-control is NUL
a820: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74  L. However, if t
a830: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
a840: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64   is being synced
a850: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61  .** as part of a
a860: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20   multi-database 
a870: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75  commit, the argu
a880: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
a890: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
a8a0: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
a8b0: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63  ning the transac
a8c0: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75  tions master-jou
a8d0: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20  rnal file name. 
a8e0: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64  VFSes that .** d
a8f0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
a900: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69  signal should si
a910: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
a920: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
a930: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75  cations .** shou
a940: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
a950: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
a960: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
a970: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
a980: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70  o may .** disrup
a990: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
a9a0: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
a9b0: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
a9c0: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
a9d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a9e0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
a9f0: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65  HASETWO]].** The
aa00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
aa10: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20  OMMIT_PHASETWO] 
aa20: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
aa30: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
aa40: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
aa50: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
aa60: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74  after a transact
aa70: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ion has been com
aa80: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65  mitted immediate
aa90: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65  ly.** but before
aaa0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
aab0: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73   unlocked. VFSes
aac0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65   that do not nee
aad0: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a  d this signal.**
aae0: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
aaf0: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
ab00: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
ab10: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
ab20: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  l.** [sqlite3_fi
ab30: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
ab40: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
ab50: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
ab60: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f  isrupt the .** o
ab70: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
ab80: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
ab90: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
aba0: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
abb0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
abc0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
abd0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
abe0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
abf0: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69  _RETRY] opcode i
ac00: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
ac10: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  ure automatic.**
ac20: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e   retry counts an
ac30: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20  d intervals for 
ac40: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f  certain disk I/O
ac50: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20   operations for 
ac60: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b  the.** windows [
ac70: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
ac80: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e   provide robustn
ac90: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65  ess in the prese
aca0: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76  nce of.** anti-v
acb0: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
acc0: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
acd0: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
ace0: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
acf0: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
ad00: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
ad10: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
ad20: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
ad30: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
ad40: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
ad50: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
ad60: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
ad70: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
ad80: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
ad90: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
ada0: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
adb0: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
adc0: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
add0: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65  ode allows these
ade0: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20   two values (10 
adf0: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
ae00: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
ae10: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
ae20: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
ae30: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
ae40: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
ae50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
ae60: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
ae70: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
ae80: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
ae90: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
aea0: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
aeb0: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
aec0: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68  rst integer i th
aed0: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
aee0: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
aef0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
af00: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
af10: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
af20: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
af30: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
af40: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
af50: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
af60: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
af70: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
af80: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
af90: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
afa0: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
afb0: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
afc0: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
afd0: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
afe0: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
aff0: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
b000: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b010: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
b020: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
b030: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
b040: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
b050: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
b060: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
b070: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
b080: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
b090: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
b0a0: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
b0b0: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
b0c0: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
b0d0: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
b0e0: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
b0f0: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
b100: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
b110: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
b120: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
b130: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
b140: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
b150: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
b160: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
b170: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
b180: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
b190: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
b1a0: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
b1b0: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
b1c0: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
b1d0: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
b1e0: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
b1f0: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
b200: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
b210: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
b220: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
b230: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
b240: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
b250: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
b260: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
b270: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
b280: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
b290: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
b2a0: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
b2b0: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
b2c0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
b2d0: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
b2e0: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
b2f0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
b300: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
b310: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
b320: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
b330: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
b340: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
b350: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
b360: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
b370: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
b380: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
b390: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
b3a0: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
b3b0: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
b3c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b3d0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
b3e0: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
b3f0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b400: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
b410: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
b420: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
b430: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
b440: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
b450: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
b460: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
b470: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
b480: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
b490: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
b4a0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
b4b0: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
b4c0: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
b4d0: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
b4e0: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
b4f0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
b500: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
b510: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
b520: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
b530: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
b540: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
b550: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
b560: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
b570: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
b580: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
b590: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
b5a0: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
b5b0: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
b5c0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
b5d0: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
b5e0: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
b5f0: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
b600: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b610: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
b620: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
b630: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
b640: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
b650: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
b660: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
b670: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
b680: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
b690: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
b6a0: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
b6b0: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
b6c0: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
b6d0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
b6e0: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
b6f0: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
b700: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
b710: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
b720: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
b730: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
b740: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
b750: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
b760: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
b770: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
b780: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
b790: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
b7a0: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
b7b0: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
b7c0: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
b7d0: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
b7e0: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
b7f0: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
b800: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
b810: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
b820: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
b830: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
b840: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
b850: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
b860: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
b870: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
b880: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
b890: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
b8a0: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
b8b0: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
b8c0: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
b8d0: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
b8e0: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
b8f0: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
b900: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
b910: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
b920: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
b930: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
b940: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
b950: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
b960: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
b970: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
b980: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
b990: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
b9a0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
b9b0: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
b9c0: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
b9d0: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
b9e0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
b9f0: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
ba00: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
ba10: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ba20: 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20  ]].** ^Whenever 
ba30: 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  a [PRAGMA] state
ba40: 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20  ment is parsed, 
ba50: 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  an [SQLITE_FCNTL
ba60: 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c  _PRAGMA] .** fil
ba70: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e  e control is sen
ba80: 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73  t to the open [s
ba90: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
baa0: 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  ect correspondin
bab0: 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61  g.** to the data
bac0: 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69  base file to whi
bad0: 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74  ch the pragma st
bae0: 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20  atement refers. 
baf0: 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ^The argument.**
bb00: 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   to the [SQLITE_
bb10: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
bb20: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e  le control is an
bb30: 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69   array of.** poi
bb40: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
bb50: 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69   (char**) in whi
bb60: 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c  ch the second el
bb70: 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72  ement of the arr
bb80: 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ay.** is the nam
bb90: 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  e of the pragma 
bba0: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c  and the third el
bbb0: 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67  ement is the arg
bbc0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  ument to the.** 
bbd0: 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69  pragma or NULL i
bbe0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73  f the pragma has
bbf0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e   no argument.  ^
bc00: 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  The handler for 
bc10: 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  an.** [SQLITE_FC
bc20: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
bc30: 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74   control can opt
bc40: 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65  ionally make the
bc50: 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a   first element.*
bc60: 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20  * of the char** 
bc70: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74  argument point t
bc80: 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69  o a string obtai
bc90: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
bca0: 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20  3_mprintf()].** 
bcb0: 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
bcc0: 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e  t and that strin
bcd0: 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  g will become th
bce0: 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
bcf0: 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65  pragma or.** the
bd00: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
bd10: 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69  f the pragma fai
bd20: 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  ls. ^If the.** [
bd30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
bd40: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
bd50: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
bd60: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65  E_NOTFOUND], the
bd70: 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52  n normal .** [PR
bd80: 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67  AGMA] processing
bd90: 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66   continues.  ^If
bda0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
bdb0: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
bdc0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
bdd0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
bde0: 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20  then the parser 
bdf0: 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
be00: 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64  .** VFS has hand
be10: 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69  led the PRAGMA i
be20: 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61  tself and the pa
be30: 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61  rser generates a
be40: 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72   no-op.** prepar
be50: 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ed statement.  ^
be60: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
be70: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
be80: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
be90: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
bea0: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
beb0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
bec0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
bed0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
bee0: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
bef0: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
bf00: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
bf10: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
bf20: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
bf30: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
bf40: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
bf50: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
bf60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
bf70: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
bf80: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
bf90: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
bfa0: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
bfb0: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
bfc0: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
bfd0: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
bfe0: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
bff0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
c000: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c010: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
c020: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
c030: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
c040: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
c050: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
c060: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
c070: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
c080: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
c090: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
c0a0: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
c0b0: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
c0c0: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
c0d0: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
c0e0: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
c0f0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
c100: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
c110: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
c120: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
c130: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
c140: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
c150: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
c160: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
c170: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
c180: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
c190: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
c1a0: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
c1b0: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
c1c0: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
c1d0: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
c1e0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
c1f0: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
c200: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
c210: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
c220: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
c230: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
c240: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
c250: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
c260: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
c270: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
c280: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
c290: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
c2a0: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
c2b0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
c2c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
c2d0: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
c2e0: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
c2f0: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
c300: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
c310: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
c320: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
c330: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
c340: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
c350: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
c360: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
c370: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
c380: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
c390: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
c3a0: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
c3b0: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
c3c0: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
c3d0: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
c3e0: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
c3f0: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
c400: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
c410: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
c420: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
c430: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
c440: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
c450: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
c460: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
c470: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
c480: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
c490: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
c4a0: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
c4b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c4c0: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
c4d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c4e0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
c4f0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
c500: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
c510: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
c520: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
c530: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
c540: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
c550: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
c560: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
c570: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
c580: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
c590: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
c5a0: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
c5b0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
c5c0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
c5d0: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
c5e0: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
c5f0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
c600: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
c610: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
c620: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
c630: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
c640: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
c650: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
c660: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
c670: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
c680: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
c690: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
c6a0: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
c6b0: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
c6c0: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
c6d0: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
c6e0: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
c6f0: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
c700: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
c710: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
c720: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
c730: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
c740: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
c750: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
c760: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
c770: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
c780: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
c790: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
c7a0: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
c7b0: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
c7c0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
c7d0: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
c7e0: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
c7f0: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
c800: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
c810: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
c820: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
c830: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
c840: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
c850: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
c860: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
c870: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
c880: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
c890: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
c8a0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
c8b0: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
c8c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c8d0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
c8e0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c8f0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
c900: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
c910: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
c920: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
c930: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
c940: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
c950: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
c960: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
c970: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
c980: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
c990: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
c9a0: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
c9b0: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
c9c0: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
c9d0: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f  opened..**.** </
c9e0: 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ul>.*/.#define S
c9f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
ca00: 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20  STATE           
ca10: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
ca20: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
ca30: 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20  XYFILE          
ca40: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
ca50: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
ca60: 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20  YFILE           
ca70: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
ca80: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
ca90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
caa0: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
cab0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
cac0: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
cad0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
cae0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
caf0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  E              6
cb00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cb10: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
cb20: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a  ER            7.
cb30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cb40: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
cb50: 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23  D            8.#
cb60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cb70: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
cb80: 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  RY          9.#d
cb90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cba0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20  TL_PERSIST_WAL  
cbb0: 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
cbc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cbd0: 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20  L_OVERWRITE     
cbe0: 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66           11.#def
cbf0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cc00: 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20  _VFSNAME        
cc10: 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69          12.#defi
cc20: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cc30: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
cc40: 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e  ITE    13.#defin
cc50: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
cc60: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
cc70: 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65        14.#define
cc80: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55   SQLITE_FCNTL_BU
cc90: 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20  SYHANDLER       
cca0: 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20       15.#define 
ccb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
ccc0: 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20  PFILENAME       
ccd0: 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
cce0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
ccf0: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
cd00: 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51     18.#define SQ
cd10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
cd20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
cd30: 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c    19.#define SQL
cd40: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
cd50: 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  VED             
cd60: 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   20.#define SQLI
cd70: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20  TE_FCNTL_SYNC   
cd80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
cd90: 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  21.#define SQLIT
cda0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
cdb0: 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32  HASETWO        2
cdc0: 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  2../*.** CAPI3RE
cdd0: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
cde0: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
cdf0: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
ce00: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
ce10: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
ce20: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
ce30: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
ce40: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
ce50: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
ce60: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
ce70: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
ce80: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
ce90: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
cea0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
ceb0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
cec0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
ced0: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
cee0: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
cef0: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
cf00: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
cf10: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
cf20: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
cf30: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
cf40: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
cf50: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
cf60: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
cf70: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
cf80: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
cf90: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
cfa0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
cfb0: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
cfc0: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
cfd0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
cfe0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
cff0: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
d000: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
d010: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
d020: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
d030: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
d040: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
d050: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
d060: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
d070: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
d080: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
d090: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
d0a0: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
d0b0: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
d0c0: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
d0d0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
d0e0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
d0f0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
d100: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
d110: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
d120: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
d130: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
d140: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
d150: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
d160: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
d170: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
d180: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
d190: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
d1a0: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
d1b0: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
d1c0: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
d1d0: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
d1e0: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
d1f0: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
d200: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
d210: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
d220: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
d230: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
d240: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
d250: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
d260: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
d270: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
d280: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
d290: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
d2a0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
d2b0: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
d2c0: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
d2d0: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
d2e0: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
d2f0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
d300: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
d310: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
d320: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
d330: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
d340: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
d350: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
d360: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
d370: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
d380: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
d390: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
d3a0: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
d3b0: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
d3c0: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
d3d0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
d3e0: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
d3f0: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
d400: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
d410: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
d420: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
d430: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
d440: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
d450: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
d460: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
d470: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
d480: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
d490: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
d4a0: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
d4b0: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
d4c0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
d4d0: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
d4e0: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
d4f0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
d500: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
d510: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
d520: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
d530: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
d540: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
d550: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
d560: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
d570: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
d580: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
d590: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
d5a0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
d5b0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
d5c0: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
d5d0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
d5e0: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
d5f0: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
d600: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
d610: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
d620: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
d630: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
d640: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
d650: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
d660: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
d670: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
d680: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
d690: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
d6a0: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
d6b0: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
d6c0: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
d6d0: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   11 alphanumeric
d6e0: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
d6f0: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
d700: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
d710: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
d720: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
d730: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
d740: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
d750: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
d760: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
d770: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
d780: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
d790: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
d7a0: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
d7b0: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
d7c0: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
d7d0: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
d7e0: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
d7f0: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
d800: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
d810: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
d820: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
d830: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
d840: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
d850: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
d860: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
d870: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
d880: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
d890: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
d8a0: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
d8b0: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
d8c0: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
d8d0: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
d8e0: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
d8f0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
d900: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
d910: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
d920: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
d930: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
d940: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
d950: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
d960: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
d970: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
d980: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
d990: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
d9a0: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
d9b0: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
d9c0: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
d9d0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
d9e0: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
d9f0: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
da00: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
da10: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
da20: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
da30: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
da40: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
da50: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
da60: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
da70: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
da80: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
da90: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
daa0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
dab0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
dac0: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
dad0: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
dae0: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
daf0: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
db00: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
db10: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
db20: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
db30: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
db40: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
db50: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
db60: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
db70: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
db80: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
db90: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
dba0: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
dbb0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
dbc0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
dbd0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
dbe0: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
dbf0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
dc00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
dc10: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
dc20: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
dc30: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
dc40: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
dc50: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
dc60: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
dc70: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
dc80: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
dc90: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
dca0: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
dcb0: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
dcc0: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
dcd0: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
dce0: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
dcf0: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
dd00: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
dd10: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
dd20: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
dd30: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
dd40: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
dd50: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
dd60: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
dd70: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
dd80: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
dd90: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
dda0: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
ddb0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
ddc0: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
ddd0: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
dde0: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
ddf0: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
de00: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
de10: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
de20: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
de30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
de40: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
de50: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
de60: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
de70: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
de80: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
de90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
dea0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
deb0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
dec0: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
ded0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
dee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
def0: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
df00: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
df10: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
df20: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
df30: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
df40: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
df50: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
df60: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
df70: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
df80: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
df90: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
dfa0: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
dfb0: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
dfc0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
dfd0: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
dfe0: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
dff0: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
e000: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
e010: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
e020: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
e030: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
e040: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
e050: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
e060: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
e070: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
e080: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
e090: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
e0a0: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
e0b0: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
e0c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
e0d0: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
e0e0: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
e0f0: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
e100: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
e110: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
e120: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
e130: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
e140: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
e150: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
e160: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
e170: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
e180: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
e190: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
e1a0: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
e1b0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
e1c0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
e1d0: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
e1e0: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
e1f0: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
e200: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
e210: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
e220: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
e230: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
e240: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
e250: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
e260: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
e270: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
e280: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
e290: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
e2a0: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
e2b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
e2c0: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
e2d0: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
e2e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
e2f0: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
e300: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
e310: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
e320: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
e330: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
e340: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
e350: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
e360: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
e370: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
e380: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
e390: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
e3a0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
e3b0: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
e3c0: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
e3d0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
e3e0: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
e3f0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
e400: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
e410: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
e420: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
e430: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
e440: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
e450: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
e460: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
e470: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
e480: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
e490: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
e4a0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
e4b0: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
e4c0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
e4d0: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
e4e0: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
e4f0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
e500: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
e510: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
e520: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
e530: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
e540: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
e550: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
e560: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
e570: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
e580: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
e590: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
e5a0: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
e5b0: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
e5c0: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
e5d0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
e5e0: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
e5f0: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
e600: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
e610: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
e620: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
e630: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
e640: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
e650: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
e660: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
e670: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
e680: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
e690: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
e6a0: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
e6b0: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
e6c0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
e6d0: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
e6e0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
e6f0: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
e700: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
e710: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
e720: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
e730: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
e740: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
e750: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
e760: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
e770: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
e780: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
e790: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
e7a0: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
e7b0: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
e7c0: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
e7d0: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
e7e0: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
e7f0: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
e800: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
e810: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
e820: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
e830: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
e840: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
e850: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
e860: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
e870: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
e880: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
e890: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
e8a0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
e8b0: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
e8c0: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
e8d0: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
e8e0: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
e8f0: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
e900: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
e910: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
e920: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
e930: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
e940: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
e950: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
e960: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
e970: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30  lied by 86400000
e980: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
e990: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
e9a0: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
e9b0: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
e9c0: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
e9d0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
e9e0: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
e9f0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
ea00: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
ea10: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
ea20: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
ea30: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
ea40: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
ea50: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
ea60: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
ea70: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
ea80: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
ea90: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
eaa0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
eab0: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
eac0: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
ead0: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
eae0: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
eaf0: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
eb00: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
eb10: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
eb20: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
eb30: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
eb40: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
eb50: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
eb60: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
eb70: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
eb80: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
eb90: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
eba0: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
ebb0: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
ebc0: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
ebd0: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
ebe0: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
ebf0: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
ec00: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
ec10: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
ec20: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
ec30: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
ec40: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
ec50: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
ec60: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
ec70: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
ec80: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
ec90: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
eca0: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
ecb0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
ecc0: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
ecd0: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
ece0: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
ecf0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
ed00: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
ed10: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
ed20: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
ed30: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
ed40: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
ed50: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
ed60: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
ed70: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
ed80: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
ed90: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
eda0: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
edb0: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
edc0: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
edd0: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
ede0: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
edf0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
ee00: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
ee10: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
ee20: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
ee30: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
ee40: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
ee50: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
ee60: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
ee70: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
ee80: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
ee90: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
eea0: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
eeb0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
eec0: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
eed0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
eee0: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
eef0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
ef00: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
ef10: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
ef20: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
ef30: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
ef40: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
ef50: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
ef60: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
ef70: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
ef80: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
ef90: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
efa0: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
efb0: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
efc0: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
efd0: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
efe0: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
eff0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
f000: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
f010: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
f020: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
f030: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
f040: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
f050: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
f060: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
f070: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
f080: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
f090: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
f0a0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
f0b0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
f0c0: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
f0d0: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
f0e0: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
f0f0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
f100: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
f110: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
f120: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
f130: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
f140: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
f150: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
f160: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
f170: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
f180: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
f190: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
f1a0: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
f1b0: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
f1c0: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
f1d0: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
f1e0: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
f1f0: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
f200: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
f210: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
f220: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
f230: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
f240: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
f250: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
f260: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
f270: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
f280: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
f290: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
f2a0: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
f2b0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
f2c0: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
f2d0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
f2e0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
f2f0: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
f300: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
f310: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
f320: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
f330: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
f340: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
f350: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
f360: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
f370: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
f380: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
f390: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
f3a0: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
f3b0: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
f3c0: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
f3d0: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
f3e0: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
f3f0: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
f400: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
f410: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
f420: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
f430: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
f440: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
f450: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
f460: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
f470: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
f480: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
f490: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f4a0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
f4b0: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
f4c0: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
f4d0: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
f4e0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
f4f0: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
f500: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
f510: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
f520: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
f530: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
f540: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
f550: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
f560: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
f570: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
f580: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
f590: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
f5a0: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
f5b0: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
f5c0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
f5d0: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
f5e0: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
f5f0: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
f600: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
f610: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
f620: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
f630: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
f640: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f650: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
f660: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
f670: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
f680: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
f690: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
f6a0: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
f6b0: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
f6c0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
f6d0: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
f6e0: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
f6f0: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
f700: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
f710: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
f720: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f730: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
f740: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
f750: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
f760: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
f770: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
f780: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
f790: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
f7a0: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
f7b0: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
f7c0: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
f7d0: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
f7e0: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
f7f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f800: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
f810: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
f820: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
f830: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
f840: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
f850: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
f860: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
f870: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
f880: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
f890: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
f8a0: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
f8b0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
f8c0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
f8d0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
f8e0: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
f8f0: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
f900: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
f910: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
f920: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
f930: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
f940: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
f950: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
f960: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
f970: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
f980: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
f990: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
f9a0: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
f9b0: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
f9c0: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
f9d0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
f9e0: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
f9f0: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
fa00: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
fa10: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
fa20: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
fa30: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
fa40: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
fa50: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
fa60: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
fa70: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
fa80: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
fa90: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
faa0: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
fab0: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
fac0: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
fad0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
fae0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
faf0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
fb00: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
fb10: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
fb20: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
fb30: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
fb40: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
fb50: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
fb60: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
fb70: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
fb80: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
fb90: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
fba0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
fbb0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
fbc0: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
fbd0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
fbe0: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
fbf0: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
fc00: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
fc10: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
fc20: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20  ** was given no 
fc30: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
fc40: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
fc50: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
fc60: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
fc70: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
fc80: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
fc90: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
fca0: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
fcb0: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
fcc0: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
fcd0: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
fce0: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
fcf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
fd00: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
fd10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fd20: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
fd30: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
fd40: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
fd50: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
fd60: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
fd70: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
fd80: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
fd90: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
fda0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
fdb0: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
fdc0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
fdd0: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
fde0: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
fdf0: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
fe00: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
fe10: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
fe20: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
fe30: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
fe40: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
fe50: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
fe60: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
fe70: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
fe80: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
fe90: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
fea0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
feb0: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
fec0: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
fed0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
fee0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
fef0: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
ff00: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
ff10: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
ff20: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ff30: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
ff40: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
ff50: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
ff60: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
ff70: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ff80: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
ff90: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
ffa0: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
ffb0: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
ffc0: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
ffd0: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
ffe0: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
fff0: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
10000 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
10010 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
10020 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
10030 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
10040 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
10050 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
10060 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10070 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
10080 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
10090 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
100a0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
100b0 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
100c0 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
100d0 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
100e0 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
100f0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
10100 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
10110 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
10120 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
10130 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
10140 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
10150 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
10160 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
10170 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10180 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
10190 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
101a0 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
101b0 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
101c0 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
101d0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
101e0 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
101f0 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
10200 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
10210 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
10220 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10230 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
10240 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
10250 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
10260 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
10270 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
10280 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
10290 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
102a0 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
102b0 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
102c0 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
102d0 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
102e0 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
102f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
10300 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
10310 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
10320 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
10330 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
10340 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
10350 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
10360 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
10370 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
10380 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
10390 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
103a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
103b0 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
103c0 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
103d0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
103e0 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
103f0 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
10400 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
10410 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10420 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
10430 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
10440 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10450 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
10460 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
10470 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
10480 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
10490 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
104a0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
104b0 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
104c0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
104d0 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
104e0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
104f0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
10500 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
10510 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
10520 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
10530 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
10540 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
10550 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
10560 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
10570 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
10580 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
10590 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
105a0 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
105b0 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
105c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
105d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
105e0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
105f0 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
10600 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
10610 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
10620 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
10630 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
10640 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
10650 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
10660 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
10670 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
10680 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
10690 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
106a0 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
106b0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
106c0 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
106d0 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
106e0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
106f0 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
10700 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
10710 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
10720 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
10730 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
10740 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
10750 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
10760 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
10770 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
10780 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
10790 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
107a0 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
107b0 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
107c0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
107d0 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
107e0 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
107f0 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
10800 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10810 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
10820 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
10830 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
10840 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
10850 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
10860 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
10870 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
10880 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
10890 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
108a0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
108b0 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
108c0 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
108d0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
108e0 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
108f0 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
10900 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
10910 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
10920 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
10930 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
10940 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
10950 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
10960 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
10970 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
10980 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
10990 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
109a0 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
109b0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
109c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
109d0 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
109e0 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
109f0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
10a00 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
10a10 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
10a20 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
10a30 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
10a40 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
10a50 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
10a60 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
10a70 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
10a80 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
10a90 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
10aa0 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
10ab0 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
10ac0 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
10ad0 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
10ae0 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
10af0 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
10b00 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
10b10 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
10b20 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
10b30 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
10b40 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
10b50 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
10b60 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
10b70 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
10b80 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
10b90 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
10ba0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10bb0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
10bc0 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
10bd0 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
10be0 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
10bf0 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
10c00 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
10c10 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
10c20 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
10c30 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
10c40 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
10c50 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
10c60 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
10c70 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
10c80 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
10c90 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
10ca0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10cb0 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
10cc0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
10cd0 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
10ce0 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
10cf0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
10d00 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
10d10 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
10d20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
10d30 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
10d40 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
10d50 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
10d60 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
10d70 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
10d80 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
10d90 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
10da0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
10db0 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
10dc0 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
10dd0 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
10de0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
10df0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
10e00 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
10e10 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
10e20 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
10e30 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
10e40 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
10e50 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
10e60 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
10e70 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
10e80 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
10e90 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
10ea0 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
10eb0 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
10ec0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
10ed0 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
10ee0 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51  ialize(void);.SQ
10ef0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
10f00 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
10f10 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
10f20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  int sqlite3_os_i
10f30 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nit(void);.SQLIT
10f40 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
10f50 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
10f60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10f70 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
10f80 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
10f90 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
10fa0 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
10fb0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
10fc0 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
10fd0 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
10fe0 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
10ff0 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
11000 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
11010 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
11020 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
11030 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
11040 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
11050 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
11060 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
11070 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
11080 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
11090 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
110a0 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
110b0 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
110c0 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
110d0 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
110e0 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
110f0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
11100 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
11110 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
11120 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
11130 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
11140 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
11150 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
11160 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
11170 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
11180 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
11190 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
111a0 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
111b0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
111c0 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
111d0 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
111e0 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
111f0 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
11200 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
11210 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
11220 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
11230 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11240 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
11250 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
11260 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
11270 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11280 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
11290 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
112a0 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
112b0 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
112c0 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
112d0 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
112e0 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
112f0 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
11300 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
11310 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
11320 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
11330 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
11340 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
11350 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
11360 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
11370 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
11380 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
11390 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
113a0 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
113b0 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
113c0 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
113d0 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
113e0 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
113f0 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
11400 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
11410 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
11420 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
11430 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
11440 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
11450 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
11460 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
11470 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
11480 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
11490 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
114a0 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
114b0 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
114c0 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
114d0 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
114e0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
114f0 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
11500 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
11510 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
11520 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
11530 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
11540 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
11550 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20  figure database 
11560 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  connections.**.*
11570 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
11580 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
11590 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
115a0 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
115b0 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
115c0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
115d0 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
115e0 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
115f0 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
11600 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
11610 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
11620 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
11630 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
11640 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
11650 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
11660 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
11670 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
11680 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
11690 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
116a0 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
116b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
116c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
116d0 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
116e0 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
116f0 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
11700 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
11710 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
11720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11730 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
11740 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
11750 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
11760 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
11770 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
11780 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
11790 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
117a0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
117b0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
117c0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
117d0 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
117e0 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
117f0 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
11800 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  PI int sqlite3_d
11810 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
11820 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
11830 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11840 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
11850 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a  ion Routines.**.
11860 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
11870 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65  f this object de
11880 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
11890 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69  ace between SQLi
118a0 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65  te.** and low-le
118b0 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
118c0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a  ation routines..
118d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  **.** This objec
118e0 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c  t is used in onl
118f0 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74  y one place in t
11900 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  he SQLite interf
11910 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ace..** A pointe
11920 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
11930 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
11940 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
11950 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
11960 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68  onfig()] when th
11970 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
11980 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51  option is.** [SQ
11990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
119a0 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  OC] or [SQLITE_C
119b0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
119c0 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69  .  .** By creati
119d0 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ng an instance o
119e0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a  f this object.**
119f0 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20   and passing it 
11a00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
11a10 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
11a20 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64  IG_MALLOC]).** d
11a30 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  uring configurat
11a40 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ion, an applicat
11a50 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20  ion can specify 
11a60 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
11a70 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
11a80 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f  ion subsystem fo
11a90 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20  r SQLite to use 
11aa0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a  for all of its.*
11ab0 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  * dynamic memory
11ac0 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   needs..**.** No
11ad0 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  te that SQLite c
11ae0 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61  omes with severa
11af0 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  l [built-in memo
11b00 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a  ry allocators].*
11b10 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65  * that are perfe
11b20 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f  ctly adequate fo
11b30 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69  r the overwhelmi
11b40 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61  ng majority of a
11b50 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
11b60 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a  nd that this obj
11b70 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66  ect is only usef
11b80 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e  ul to a tiny min
11b90 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
11ba0 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70  tions.** with sp
11bb0 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79  ecialized memory
11bc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
11bd0 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20  irements.  This 
11be0 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73  object is.** als
11bf0 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  o used during te
11c00 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20  sting of SQLite 
11c10 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63  in order to spec
11c20 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
11c30 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
11c40 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75  ocator that simu
11c50 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74  lates memory out
11c60 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69  -of-memory condi
11c70 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65  tions in.** orde
11c80 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  r to verify that
11c90 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73   SQLite recovers
11ca0 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d   gracefully from
11cb0 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69   such.** conditi
11cc0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ons..**.** The x
11cd0 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63  Malloc, xRealloc
11ce0 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68  , and xFree meth
11cf0 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
11d00 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
11d10 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  (), realloc() an
11d20 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
11d30 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
11d40 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
11d50 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
11d60 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73  ntees that the s
11d70 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
11d80 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73  o.** xRealloc is
11d90 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20   always a value 
11da0 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72  returned by a pr
11db0 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75  ior call to xRou
11dc0 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a  ndup..**.** xSiz
11dd0 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
11de0 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
11df0 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61  ze of a memory a
11e00 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65  llocation.** pre
11e10 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
11e20 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72   from xMalloc or
11e30 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20   xRealloc.  The 
11e40 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a  allocated size.*
11e50 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c  * is always at l
11e60 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74  east as big as t
11e70 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  he requested siz
11e80 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  e but may be lar
11e90 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ger..**.** The x
11ea0 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72  Roundup method r
11eb0 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c  eturns what woul
11ec0 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  d be the allocat
11ed0 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20  ed size of.** a 
11ee0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11ef0 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63  n given a partic
11f00 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73  ular requested s
11f10 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72  ize.  Most memor
11f20 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20  y.** allocators 
11f30 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20  round up memory 
11f40 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c  allocations at l
11f50 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74  east to the next
11f60 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20   multiple.** of 
11f70 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74  8.  Some allocat
11f80 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20  ors round up to 
11f90 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c  a larger multipl
11fa0 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20  e or to a power 
11fb0 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d  of 2..** Every m
11fc0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11fd0 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20   request coming 
11fe0 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69  in through [sqli
11ff0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  te3_malloc()].**
12000 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
12010 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61  lloc()] first ca
12020 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49  lls xRoundup.  I
12030 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72  f xRoundup retur
12040 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63  ns 0, .** that c
12050 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73  auses the corres
12060 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61  ponding memory a
12070 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69  llocation to fai
12080 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e  l..**.** The xIn
12090 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61  it method initia
120a0 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  lizes the memory
120b0 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72   allocator.  For
120c0 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
120d0 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
120e0 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
120f0 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
12100 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
12110 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
12120 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
12130 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
12140 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
12150 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
12160 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
12170 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
12180 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
12190 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
121a0 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
121b0 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
121c0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
121d0 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
121e0 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
121f0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
12200 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
12210 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
12220 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
12230 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
12240 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
12250 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
12260 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
12270 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
12280 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
12290 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
122a0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
122b0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
122c0 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
122d0 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
122e0 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
122f0 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
12300 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
12310 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
12320 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
12330 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
12340 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
12350 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
12360 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
12370 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
12380 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
12390 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
123a0 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
123b0 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
123c0 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
123d0 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
123e0 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
123f0 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
12400 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
12410 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
12420 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
12430 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
12440 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
12450 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
12460 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
12470 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
12480 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
12490 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
124a0 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
124b0 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
124c0 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
124d0 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
124e0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
124f0 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
12500 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
12510 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
12520 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
12530 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
12540 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
12550 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
12560 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
12570 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
12580 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
12590 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
125a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
125b0 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
125c0 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
125d0 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
125e0 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
125f0 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
12600 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
12610 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
12620 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
12630 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
12640 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
12650 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
12660 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
12670 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
12680 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
12690 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
126a0 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
126b0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
126c0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
126d0 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
126e0 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
126f0 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
12700 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
12710 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
12720 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
12730 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
12740 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
12750 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
12760 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12770 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
12780 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  Options.** KEYWO
12790 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74  RDS: {configurat
127a0 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a  ion option}.**.*
127b0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
127c0 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
127d0 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
127e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
127f0 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
12800 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
12810 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
12820 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
12830 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
12840 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
12850 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12860 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
12870 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
12880 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
12890 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
128a0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
128b0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
128c0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
128d0 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
128e0 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
128f0 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
12900 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
12910 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
12920 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
12930 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
12940 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
12950 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
12960 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
12970 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
12980 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
12990 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
129a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
129b0 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
129c0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
129d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
129e0 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64  INGLETHREAD]] <d
129f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12a00 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74  SINGLETHREAD</dt
12a10 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
12a20 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
12a30 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
12a40 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
12a50 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
12a60 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69  ding mode] to Si
12a70 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e  ngle-thread.  In
12a80 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
12a90 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
12aa0 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
12ab0 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
12ac0 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
12ad0 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
12ae0 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
12af0 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c  hread.   ^If SQL
12b00 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12b10 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
12b20 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
12b30 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
12b40 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
12b50 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
12b60 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
12b70 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74  ible to change t
12b80 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
12b90 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66  de] from its def
12ba0 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  ault.** value of
12bb0 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61   Single-thread a
12bc0 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nd so [sqlite3_c
12bd0 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
12be0 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  turn .** [SQLITE
12bf0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
12c00 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
12c10 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
12c20 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75  HREAD.** configu
12c30 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
12c40 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12c50 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
12c60 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
12c70 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
12c80 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
12c90 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
12ca0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
12cb0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
12cc0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
12cd0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
12ce0 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72  de] to Multi-thr
12cf0 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
12d00 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
12d10 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
12d20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12d30 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
12d40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
12d50 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
12d60 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
12d70 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
12d80 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
12d90 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
12da0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
12db0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
12dc0 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
12dd0 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
12de0 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
12df0 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
12e00 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
12e10 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
12e20 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
12e30 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20  t as long as no 
12e40 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65  two threads atte
12e50 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73  mpt to use the s
12e60 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ame.** [database
12e70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
12e80 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20  the same time.  
12e90 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
12ea0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
12eb0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
12ec0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
12ed0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
12ee0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
12ef0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
12f00 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
12f10 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72  et the Multi-thr
12f20 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
12f30 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
12f40 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
12f50 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
12f60 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
12f70 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
12f80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
12f90 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67  LTITHREAD config
12fa0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
12fb0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12fc0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
12fd0 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  LIZED]] <dt>SQLI
12fe0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
12ff0 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
13000 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
13010 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
13020 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
13030 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
13040 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
13050 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64  e] to Serialized
13060 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
13070 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e  , this option en
13080 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
13090 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74  exes including t
130a0 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20  he recursive.** 
130b0 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61  mutexes on [data
130c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
130d0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
130e0 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
130f0 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f  s..** In this mo
13100 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65  de (which is the
13110 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51   default when SQ
13120 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
13130 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45   with.** [SQLITE
13140 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20  _THREADSAFE=1]) 
13150 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
13160 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73  ry will itself s
13170 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a  erialize access.
13180 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20  ** to [database 
13190 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
131a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
131b0 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74  ments] so that t
131c0 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
131d0 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65  n is free to use
131e0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
131f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13200 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b  or the.** same [
13210 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
13220 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74  nt] in different
13230 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
13240 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49  same time..** ^I
13250 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
13260 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
13270 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13280 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
13290 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
132a0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
132b0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
132c0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
132d0 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20   the Serialized 
132e0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
132f0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
13300 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
13310 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
13320 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
13330 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
13340 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
13350 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69  IZED configurati
13360 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
13370 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13380 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c  ONFIG_MALLOC]] <
13390 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
133a0 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
133b0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
133c0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
133d0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
133e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
133f0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
13400 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
13410 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
13420 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
13430 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
13440 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
13450 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
13460 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
13470 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
13480 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
13490 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
134a0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
134b0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
134c0 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
134d0 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
134e0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
134f0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
13500 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
13510 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
13520 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
13530 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
13540 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
13550 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13560 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
13570 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
13580 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
13590 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
135a0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
135b0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
135c0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
135d0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
135e0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
135f0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
13600 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
13610 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
13620 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
13630 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
13640 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
13650 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
13660 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
13670 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
13680 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
13690 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
136a0 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65  d the default me
136b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
136c0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
136d0 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20   a wrapper that 
136e0 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f  simulations memo
136f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
13700 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63  ilure or.** trac
13710 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c  ks memory usage,
13720 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f   for example. </
13730 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13740 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
13750 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TUS]] <dt>SQLITE
13760 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
13770 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  S</dt>.** <dd> ^
13780 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
13790 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
137a0 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69  t of type int, i
137b0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
137c0 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  .** boolean, whi
137d0 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
137e0 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
137f0 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20  ction of memory 
13800 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73  allocation .** s
13810 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65  tatistics. ^(Whe
13820 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
13830 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
13840 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  re disabled, the
13850 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   .** following S
13860 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
13870 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
13880 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
13890 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
138a0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
138b0 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
138c0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
138d0 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
138e0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
138f0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
13900 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
13910 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
13920 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
13930 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
13940 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
13950 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
13960 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
13970 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
13980 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
13990 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
139a0 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
139b0 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
139c0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
139d0 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
139e0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
139f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13a00 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13a10 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  CH]] <dt>SQLITE_
13a20 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
13a30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
13a40 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
13a50 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
13a60 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
13a70 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
13a80 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  r.** scratch mem
13a90 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20  ory.  There are 
13aa0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
13ab0 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38    A pointer an 8
13ac0 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
13ad0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66   memory buffer f
13ae0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63  rom which the sc
13af0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
13b00 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61  s will be.** dra
13b10 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  wn, the size of 
13b20 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c  each scratch all
13b30 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a  ocation (sz),.**
13b40 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
13b50 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74   number of scrat
13b60 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28  ch allocations (
13b70 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61  N).  The sz.** a
13b80 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
13b90 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36  a multiple of 16
13ba0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
13bb0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
13bc0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13bd0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
13be0 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
13bf0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
13c00 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
13c10 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
13c20 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20  o more than two 
13c30 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
13c40 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a  per thread.  So.
13c50 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73  ** N should be s
13c60 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20  et to twice the 
13c70 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d  expected maximum
13c80 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
13c90 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ds..** ^SQLite w
13ca0 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72  ill never requir
13cb0 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  e a scratch buff
13cc0 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
13cd0 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20  than 6.** times 
13ce0 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
13cf0 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69  e size. ^If SQLi
13d00 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61  te needs needs a
13d10 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72  dditional.** scr
13d20 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f  atch memory beyo
13d30 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
13d40 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66  ded by this conf
13d50 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13d60 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  , then .** [sqli
13d70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69  te3_malloc()] wi
13d80 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  ll be used to ob
13d90 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
13da0 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  needed.</dd>.**.
13db0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13dc0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c  IG_PAGECACHE]] <
13dd0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13de0 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
13df0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
13e00 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
13e10 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
13e20 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
13e30 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
13e40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
13e50 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
13e60 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63  e default page c
13e70 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
13e80 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63  ion.  .** This c
13e90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f  onfiguration sho
13ea0 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
13eb0 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
13ec0 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a  n-define page.**
13ed0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
13ee0 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20  ation is loaded 
13ef0 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  using the SQLITE
13f00 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
13f10 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65  option..** There
13f20 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
13f30 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
13f40 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  ion: A pointer t
13f50 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  o 8-byte aligned
13f60 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20  .** memory, the 
13f70 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
13f80 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61  e buffer (sz), a
13f90 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
13fa0 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   pages (N)..** T
13fb0 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
13fc0 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
13fd0 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
13fe0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
13ff0 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
14000 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
14010 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20  d 32768) plus a 
14020 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72  little extra for
14030 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
14040 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65  ader.  ^The page
14050 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20   header size is 
14060 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64  20 to 40 bytes d
14070 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74  epending on.** t
14080 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63  he host architec
14090 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61  ture.  ^It is ha
140a0 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
140b0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
140c0 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65  mory,.** to make
140d0 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f   sz a little too
140e0 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72   large.  The fir
140f0 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  st.** argument s
14100 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61  hould point to a
14110 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20  n allocation of 
14120 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
14130 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
14140 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
14150 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
14160 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
14170 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
14180 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
14190 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
141a0 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
141b0 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
141c0 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64  o cache.  ^If ad
141d0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
141e0 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
141f0 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
14200 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
14210 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
14220 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
14230 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
14240 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
14250 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
14260 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54  rage space..** T
14270 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68  he pointer in th
14280 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14290 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67   must.** be alig
142a0 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
142b0 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
142c0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
142d0 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69   of SQLite.** wi
142e0 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
142f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14300 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14310 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14320 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
14330 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
14340 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
14350 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
14360 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
14370 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72   will use.** for
14380 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
14390 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
143a0 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f  ation needs beyo
143b0 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65  nd those provide
143c0 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c  d.** for by [SQL
143d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
143e0 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  CH] and [SQLITE_
143f0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
14400 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  ]..** There are 
14410 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
14420 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   An 8-byte align
14430 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ed pointer to th
14440 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65  e memory,.** the
14450 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
14460 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
14470 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
14480 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
14490 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74  n size..** ^If t
144a0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
144b0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
144c0 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
144d0 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
144e0 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
144f0 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
14500 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
14510 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
14520 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
14530 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
14540 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
14550 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
14560 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49  FIG_MALLOC].  ^I
14570 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  f the.** memory 
14580 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
14590 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b  ULL and either [
145a0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
145b0 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51  MSYS3] or.** [SQ
145c0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
145d0 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64  YS5] are defined
145e0 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72  , then the alter
145f0 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a  native memory.**
14600 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e   allocator is en
14610 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  gaged to handle 
14620 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d  all of SQLites m
14630 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14640 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66   needs..** The f
14650 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
14660 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
14670 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  ) must be aligne
14680 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  d to an 8-byte.*
14690 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  * boundary or su
146a0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
146b0 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  r of SQLite will
146c0 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   be undefined..*
146d0 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  * The minimum al
146e0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73  location size is
146f0 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32   capped at 2**12
14700 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c  . Reasonable val
14710 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ues.** for the m
14720 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
14730 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20  n size are 2**5 
14740 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64  through 2**8.</d
14750 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14760 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d  E_CONFIG_MUTEX]]
14770 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14780 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
14790 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
147a0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
147b0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
147c0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
147d0 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
147e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
147f0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
14800 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
14810 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
14820 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
14830 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65  e low-level mute
14840 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  x routines to be
14850 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a   used in place.*
14860 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74  * the mutex rout
14870 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
14880 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69  SQLite.)^  ^SQLi
14890 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
148a0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e  of the.** conten
148b0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
148c0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
148d0 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72   structure befor
148e0 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  e the call to.**
148f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
14900 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66  ()] returns. ^If
14910 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14920 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
14930 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
14940 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
14950 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
14960 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
14970 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
14980 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
14990 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
149a0 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
149b0 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
149c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
149d0 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
149e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
149f0 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
14a00 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
14a10 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
14a20 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
14a30 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14a40 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64  IG_GETMUTEX]] <d
14a50 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14a60 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
14a70 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
14a80 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14a90 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
14aa0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
14ab0 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
14ac0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14ad0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
14ae0 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
14af0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
14b00 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
14b10 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
14b20 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
14b30 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
14b40 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
14b50 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
14b60 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
14b70 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
14b80 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
14b90 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
14ba0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
14bb0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
14bc0 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
14bd0 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
14be0 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
14bf0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
14c00 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
14c10 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
14c20 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
14c30 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
14c40 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
14c50 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14c60 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
14c70 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
14c80 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
14c90 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
14ca0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
14cb0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
14cc0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
14cd0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14ce0 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
14cf0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
14d00 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
14d10 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
14d20 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14d30 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14d40 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
14d50 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14d60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
14d70 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
14d80 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
14d90 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
14da0 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65  he default.** me
14db0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14dc0 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  for the lookasid
14dd0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
14de0 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64  or on each.** [d
14df0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14e00 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  on].  The first 
14e10 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
14e20 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
14e30 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
14e40 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65   slot and the se
14e50 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62  cond is the numb
14e60 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61  er of.** slots a
14e70 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68  llocated to each
14e80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
14e90 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20  tion.)^  ^(This 
14ea0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
14eb0 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  ** <i>default</i
14ec0 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
14ed0 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
14ee0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14ef0 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71  ].** verb to [sq
14f00 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
14f10 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
14f20 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
14f30 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
14f40 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
14f50 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
14f60 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s.)^ </dd>.**.**
14f70 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14f80 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  _PCACHE2]] <dt>S
14f90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14fa0 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
14fb0 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
14fc0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
14fd0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
14fe0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
14ff0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
15000 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
15010 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
15020 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  ct specifies the
15030 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
15040 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
15050 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
15060 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ion.)^  ^SQLite 
15070 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
15080 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e  the.** object an
15090 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61  d uses it for pa
150a0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
150b0 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64  allocations.</dd
150c0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
150d0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
150e0 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
150f0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15100 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
15110 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
15120 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15130 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
15140 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
15150 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
15160 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
15170 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
15180 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  s of the current
15190 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69  .** page cache i
151a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
151b0 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
151c0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
151d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
151e0 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
151f0 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
15200 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
15210 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
15220 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
15230 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
15240 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
15250 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
15260 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15270 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
15280 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
15290 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
152a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
152b0 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
152c0 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
152d0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
152e0 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
152f0 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
15300 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
15310 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
15320 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
15330 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
15340 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
15350 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
15360 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
15370 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
15380 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
15390 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
153a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
153b0 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
153c0 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
153d0 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
153e0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
153f0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
15400 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
15410 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
15420 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15430 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
15440 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
15450 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
15460 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
15470 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
15480 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
15490 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
154a0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
154b0 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
154c0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
154d0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
154e0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
154f0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
15500 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
15510 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
15520 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
15530 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
15540 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
15550 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
15560 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
15570 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
15580 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
15590 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
155a0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
155b0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
155c0 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
155d0 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
155e0 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
155f0 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
15600 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
15610 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
15620 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
15630 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
15640 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
15650 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
15660 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
15670 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
15680 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
15690 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
156a0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
156b0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
156c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
156d0 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
156e0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
156f0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
15700 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20  nt of type int. 
15710 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
15720 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e  n.** URI handlin
15730 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
15740 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
15750 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
15760 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
15770 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c  ng.** is globall
15780 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49  y disabled.)^ ^I
15790 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
157a0 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
157b0 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
157c0 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b  s.** passed to [
157d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
157e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
157f0 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  2()], [sqlite3_o
15800 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
15810 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
15820 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
15830 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
15840 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
15850 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
15860 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
15870 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
15880 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
15890 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
158a0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
158b0 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20   is opened. ^If 
158c0 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
158d0 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
158e0 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
158f0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
15900 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
15910 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
15920 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
15930 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
15940 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
15950 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55   ^(By default, U
15960 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
15970 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
15980 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
15990 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
159a0 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
159b0 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
159c0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
159d0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29  symbol defined.)
159e0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
159f0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
15a00 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
15a10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15a20 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
15a30 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73  CAN.** <dd>^This
15a40 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15a50 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 20 61  single integer a
15a60 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
15a70 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 0a   interpreted as.
15a80 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20  ** a boolean in 
15a90 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20  order to enable 
15aa0 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 75  or disable the u
15ab0 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
15ac0 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75  ndices for.** fu
15ad0 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69  ll table scans i
15ae0 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69  n the query opti
15af0 6d 69 7a 65 72 2e 20 20 5e 54 68 65 20 64 65 66  mizer.  ^The def
15b00 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20  ault setting is 
15b10 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79  determined.** by
15b20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c   the [SQLITE_ALL
15b30 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  OW_COVERING_INDE
15b40 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d  X_SCAN] compile-
15b50 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20  time option, or 
15b60 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68  is "on".** if th
15b70 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
15b80 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  option is omitte
15b90 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74  d..** The abilit
15ba0 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65  y to disable the
15bb0 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
15bc0 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
15bd0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a  l table scans.**
15be0 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65   is because some
15bf0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64   incorrectly cod
15c00 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63  ed legacy applic
15c10 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c  ations might mal
15c20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e  function.** when
15c30 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
15c40 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50  n is enabled.  P
15c50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69  roviding the abi
15c60 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62  lity to.** disab
15c70 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  le the optimizat
15c80 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f  ion allows the o
15c90 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c  lder, buggy appl
15ca0 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20  ication code to 
15cb0 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20  work.** without 
15cc0 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68  change even with
15cd0 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
15ce0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
15cf0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15d00 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49  _PCACHE]] [[SQLI
15d10 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
15d20 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  CHE]].** <dt>SQL
15d30 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15d40 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e  E and SQLITE_CON
15d50 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a  FIG_GETPCACHE.**
15d60 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69   <dd> These opti
15d70 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65  ons are obsolete
15d80 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20   and should not 
15d90 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63  be used by new c
15da0 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65  ode..** They are
15db0 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61   retained for ba
15dc0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
15dd0 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f  ility but are no
15de0 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64  w no-ops..** </d
15df0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15e00 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d  E_CONFIG_SQLLOG]
15e10 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
15e20 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a  CONFIG_SQLLOG.**
15e30 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
15e40 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
15e50 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20  le if sqlite is 
15e60 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
15e70 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
15e80 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d  BLE_SQLLOG] pre-
15e90 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
15ea0 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72  defined. The fir
15eb0 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  st argument shou
15ec0 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74  ld.** be a point
15ed0 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  er to a function
15ee0 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29   of type void(*)
15ef0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
15f00 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
15f10 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
15f20 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79   should be of ty
15f30 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20  pe (void*). The 
15f40 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
15f50 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61  ked by the libra
15f60 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73  ry.** in three s
15f70 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74  eparate circumst
15f80 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65  ances, identifie
15f90 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70  d by the value p
15fa0 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20  assed as the.** 
15fb0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15fc0 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  . If the fourth 
15fd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20  parameter is 0, 
15fe0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
15ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
16000 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
16010 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61  cond argument ha
16020 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e  s just been open
16030 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72  ed. The third ar
16040 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73  gument.** points
16050 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e   to a buffer con
16060 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65  taining the name
16070 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74   of the main dat
16080 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74  abase file. If t
16090 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
160a0 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65  ameter is 1, the
160b0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
160c0 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69  ent that the thi
160d0 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
160e0 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75  points to has ju
160f0 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64  st been executed
16100 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75  . Or, if the fou
16110 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
16120 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20   2, then.** the 
16130 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67  connection being
16140 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
16150 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
16160 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e  is being closed.
16170 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   The.** third pa
16180 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65  rameter is passe
16190 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63  d NULL In this c
161a0 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ase.  An example
161b0 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a   of using this.*
161c0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
161d0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65  option can be se
161e0 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f  en in the "test_
161f0 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65  sqllog.c" source
16200 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20   file in.** the 
16210 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65  canonical SQLite
16220 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64   source tree.</d
16230 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
16240 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
16250 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
16260 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
16270 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49  IZE.** <dd>^SQLI
16280 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
16290 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34  IZE takes two 64
162a0 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71  -bit integer (sq
162b0 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c  lite3_int64) val
162c0 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ues.** that are 
162d0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70  the default mmap
162e0 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65   size limit (the
162f0 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
16300 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   for.** [PRAGMA 
16310 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20  mmap_size]) and 
16320 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  the maximum allo
16330 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  wed mmap size li
16340 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  mit..** ^The def
16350 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e  ault setting can
16360 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62   be overridden b
16370 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  y each database 
16380 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67  connection using
16390 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b  .** either the [
163a0 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
163b0 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79  ] command, or by
163c0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53   using the.** [S
163d0 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
163e0 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74  _SIZE] file cont
163f0 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69  rol.  ^(The maxi
16400 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
16410 20 73 69 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20   size.** cannot 
16420 62 65 20 63 68 61 6e 67 65 64 20 61 74 20 72 75  be changed at ru
16430 6e 2d 74 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79  n-time.  Nor may
16440 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c   the maximum all
16450 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a  owed mmap size.*
16460 2a 20 65 78 63 65 65 64 20 74 68 65 20 63 6f 6d  * exceed the com
16470 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75  pile-time maximu
16480 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20  m mmap size set 
16490 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
164a0 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d  E_MAX_MMAP_SIZE]
164b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
164c0 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65  tion.)^.** ^If e
164d0 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74  ither argument t
164e0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  o this option is
164f0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
16500 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73  that argument is
16510 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69  .** changed to i
16520 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ts compile-time 
16530 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b  default..**.** [
16540 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  [SQLITE_CONFIG_W
16550 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a  IN32_HEAPSIZE]].
16560 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16570 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
16580 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73  IZE.** <dd>^This
16590 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
165a0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c  available if SQL
165b0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
165c0 66 6f 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 77  for Windows.** w
165d0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
165e0 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72  WIN32_MALLOC] pr
165f0 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  e-processor macr
16600 6f 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51  o defined..** SQ
16610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
16620 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73  2_HEAPSIZE takes
16630 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e   a 32-bit unsign
16640 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  ed integer value
16650 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69  .** that specifi
16660 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  es the maximum s
16670 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74  ize of the creat
16680 65 64 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c  ed heap..** </dl
16690 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
166a0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
166b0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
166c0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
166d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
166e0 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
166f0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
16700 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
16710 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
16720 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
16730 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
16740 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
16750 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
16760 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
16770 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16780 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
16790 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
167a0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
167b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
167c0 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
167d0 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
167e0 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
167f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16800 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
16810 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
16820 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
16830 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16840 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
16850 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
16860 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
16870 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
16880 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
16890 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
168a0 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
168b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
168c0 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
168d0 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
168e0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
168f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16900 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
16910 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
16920 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
16930 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
16940 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
16950 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
16960 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
16970 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
16980 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
16990 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
169a0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
169b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
169c0 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
169d0 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  4  /* no-op */.#
169e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
169f0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
16a00 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    15  /* no-op *
16a10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16a20 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
16a30 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
16a40 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  c, void* */.#def
16a50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16a60 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31  G_URI          1
16a70 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  7  /* int */.#de
16a80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16a90 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20  IG_PCACHE2      
16aa0 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  18  /* sqlite3_p
16ab0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
16ac0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16ad0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16ae0 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c  HE2   19  /* sql
16af0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
16b00 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
16b10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
16b20 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
16b30 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f  AN 20  /* int */
16b40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16b50 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20  CONFIG_SQLLOG   
16b60 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c      21  /* xSqll
16b70 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  og, void* */.#de
16b80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16b90 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  IG_MMAP_SIZE    
16ba0 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69  22  /* sqlite3_i
16bb0 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e  nt64, sqlite3_in
16bc0 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t64 */.#define S
16bd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
16be0 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20  32_HEAPSIZE     
16bf0 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74   23  /* int nByt
16c00 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e */../*.** CAPI
16c10 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
16c20 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
16c30 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
16c40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
16c50 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
16c60 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
16c70 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
16c80 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
16c90 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
16ca0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16cb0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
16cc0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
16cd0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
16ce0 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
16cf0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
16d00 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
16d10 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
16d20 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
16d30 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
16d40 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
16d50 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
16d60 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
16d70 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
16d80 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
16d90 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
16da0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
16db0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
16dc0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
16dd0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
16de0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
16df0 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
16e00 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
16e10 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
16e20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
16e30 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
16e40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16e50 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
16e60 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
16e70 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
16e80 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
16e90 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
16ea0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
16eb0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
16ec0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
16ed0 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
16ee0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
16ef0 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
16f00 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
16f10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16f20 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
16f30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
16f40 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
16f50 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
16f60 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
16f70 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
16f80 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
16f90 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
16fa0 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
16fb0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
16fc0 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
16fd0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16fe0 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
16ff0 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
17000 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
17010 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
17020 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
17030 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
17040 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
17050 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
17060 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
17070 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
17080 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
17090 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
170a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
170b0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
170c0 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
170d0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
170e0 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
170f0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
17100 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
17110 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
17120 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
17130 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
17140 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
17150 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
17160 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
17170 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
17180 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
17190 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
171a0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
171b0 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
171c0 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
171d0 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
171e0 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
171f0 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
17200 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
17210 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
17220 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
17230 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
17240 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
17250 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
17260 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
17270 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
17280 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
17290 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
172a0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
172b0 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
172c0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
172d0 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
172e0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
172f0 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
17300 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
17310 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
17320 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
17330 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
17340 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
17350 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
17360 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
17370 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
17380 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
17390 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
173a0 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
173b0 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
173c0 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
173d0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
173e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
173f0 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
17400 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
17410 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
17420 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
17430 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
17440 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
17450 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
17460 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
17470 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
17480 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
17490 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
174a0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
174b0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
174c0 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
174d0 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
174e0 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
174f0 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
17500 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
17510 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
17520 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
17530 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17540 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
17550 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
17560 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
17570 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
17580 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
17590 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
175a0 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
175b0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
175c0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
175d0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
175e0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
175f0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
17600 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
17610 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
17620 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
17630 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
17640 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
17650 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
17660 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
17670 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
17680 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
17690 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
176a0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
176b0 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
176c0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
176d0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
176e0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
176f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
17700 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
17710 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
17720 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
17730 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
17740 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
17750 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
17760 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
17770 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
17780 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
17790 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
177a0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
177b0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
177c0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
177d0 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
177e0 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
177f0 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
17800 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
17810 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
17820 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
17830 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
17840 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
17850 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
17860 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
17870 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
17880 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
17890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
178a0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
178b0 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a  E       1001  /*
178c0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
178d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
178e0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
178f0 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20  _FKEY     1002  
17900 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
17910 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
17920 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
17930 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20  IGGER  1003  /* 
17940 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
17950 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
17960 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
17970 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
17980 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Codes.**.** ^The
17990 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
179a0 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
179b0 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
179c0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
179d0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
179e0 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
179f0 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
17a00 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
17a10 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
17a20 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
17a30 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
17a40 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
17a50 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  y..*/.SQLITE_API
17a60 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74   int sqlite3_ext
17a70 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
17a80 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
17a90 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
17aa0 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
17ab0 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a  nsert Rowid.**.*
17ac0 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
17ad0 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62   most SQLite tab
17ae0 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20  les (except for 
17af0 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
17b00 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61  tables).** has a
17b10 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
17b20 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
17b30 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
17b40 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
17b50 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73  ]. ^The rowid is
17b60 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
17b70 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
17b80 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
17b90 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
17ba0 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
17bb0 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
17bc0 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
17bd0 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
17be0 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
17bf0 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65  umns. ^If.** the
17c00 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
17c10 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54  umn of type [INT
17c20 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
17c30 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  ] then that colu
17c40 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
17c50 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
17c60 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  owid..**.** ^The
17c70 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
17c80 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e  sert_rowid(D) in
17c90 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
17ca0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
17cb0 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  he .** most rece
17cc0 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  nt successful [I
17cd0 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f  NSERT] into a ro
17ce0 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69  wid table or [vi
17cf0 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
17d00 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  on database conn
17d10 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e  ection D..** ^In
17d20 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48  serts into [WITH
17d30 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
17d40 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64  s are not record
17d50 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75  ed..** ^If no su
17d60 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
17d70 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61  ]s into rowid ta
17d80 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  bles.** have eve
17d90 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
17da0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17db0 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65  ction D, .** the
17dc0 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  n sqlite3_last_i
17dd0 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72  nsert_rowid(D) r
17de0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
17df0 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
17e00 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
17e10 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77  n a trigger or w
17e20 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c  ithin a [virtual
17e30 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f   table].** metho
17e40 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  d, then this rou
17e50 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
17e60 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
17e70 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
17e80 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  row as long as t
17e90 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
17ea0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
17eb0 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  od is running..*
17ec0 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  * But once the t
17ed0 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
17ee0 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65  l table method e
17ef0 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
17f00 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
17f10 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
17f20 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
17f30 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
17f40 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
17f50 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  .** table method
17f60 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20   began.)^.**.** 
17f70 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
17f80 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
17f90 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
17fa0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
17fb0 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
17fc0 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
17fd0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
17fe0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
17ff0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
18000 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
18010 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
18020 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
18030 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
18040 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
18050 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
18060 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
18070 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
18080 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
18090 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
180a0 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
180b0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
180c0 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
180d0 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
180e0 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
180f0 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
18100 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
18110 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
18120 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
18130 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
18140 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
18150 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
18160 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
18170 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
18180 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
18190 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
181a0 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
181b0 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
181c0 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
181d0 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
181e0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
181f0 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
18200 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
18210 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
18220 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
18230 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
18240 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
18250 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
18260 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
18270 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
18280 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
18290 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
182a0 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
182b0 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
182c0 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
182d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
182e0 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
182f0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
18300 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
18310 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
18320 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
18330 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
18340 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
18350 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
18360 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
18370 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
18380 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
18390 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
183a0 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
183b0 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
183c0 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
183d0 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
183e0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
183f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
18400 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
18410 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
18420 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
18430 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
18440 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
18450 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
18460 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
18470 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
18480 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
18490 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
184a0 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
184b0 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
184c0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
184d0 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
184e0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
184f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
18500 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
18510 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
18520 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28  parameter..** ^(
18530 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
18540 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
18550 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
18560 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
18570 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
18580 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
18590 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
185a0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
185b0 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
185c0 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b  rs or [foreign k
185d0 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
185e0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55  not counted.)^ U
185f0 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
18600 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
18610 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ()] function to 
18620 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e  find the total n
18630 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
18640 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  .** including ch
18650 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
18660 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72  triggers and for
18670 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
18680 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  ..**.** ^Changes
18690 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
186a0 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79  are simulated by
186b0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
186c0 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20  trigger].** are 
186d0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e  not counted.  On
186e0 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68  ly real table ch
186f0 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
18700 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f  d..**.** ^(A "ro
18710 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
18720 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
18730 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
18740 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
18750 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
18760 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
18770 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
18780 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
18790 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
187a0 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41  ffects of [REPLA
187b0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
187c0 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f  esolution,.** ro
187d0 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72  llback, ABORT pr
187e0 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20  ocessing, [DROP 
187f0 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e  TABLE], or by an
18800 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
18810 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
18820 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
18830 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a   changes.)^.**.*
18840 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
18850 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
18860 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
18870 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
18880 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
18890 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41  cript of a [CREA
188a0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
188b0 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20  gger]. .** Most 
188c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
188d0 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
188e0 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
188f0 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
18900 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
18910 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
18920 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
18930 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
18940 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
18950 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
18960 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
18970 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
18980 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
18990 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
189a0 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
189b0 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
189c0 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
189d0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71  .** ^Calling [sq
189e0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
189f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
18a00 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f  ] recursively do
18a10 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65  es.** not create
18a20 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63   a new trigger c
18a30 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
18a40 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
18a50 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
18a60 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
18a70 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
18a80 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
18a90 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
18aa0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
18ab0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
18ac0 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
18ad0 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c  xt..**.** ^Thus,
18ae0 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
18af0 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
18b00 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
18b10 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
18b20 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
18b30 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
18b40 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
18b50 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
18b60 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
18b70 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
18b80 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74  vel.  ^(Within t
18b90 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
18ba0 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
18bb0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
18bc0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
18bd0 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
18be0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
18bf0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
18c00 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
18c10 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
18c20 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
18c30 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
18c40 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
18c50 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
18c60 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
18c70 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
18c80 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
18c90 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
18ca0 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
18cb0 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
18cc0 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
18cd0 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a  context.)^.**.**
18ce0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
18cf0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
18d00 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
18d10 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
18d20 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
18d30 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
18d40 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
18d50 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
18d60 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
18d70 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
18d80 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
18d90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
18da0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
18db0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
18dc0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
18dd0 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
18de0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
18df0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
18e00 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
18e10 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
18e20 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
18e30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18e40 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
18e50 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
18e60 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
18e70 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
18e80 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
18e90 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
18ea0 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b  y [INSERT],.** [
18eb0 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
18ec0 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73  TE] statements s
18ed0 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
18ee0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
18ef0 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28  as opened..** ^(
18f00 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  The count return
18f10 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
18f20 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  tal_changes() in
18f30 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
18f40 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b  es.** from all [
18f50 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
18f60 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
18f70 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d  ts and changes m
18f80 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69  ade by.** [forei
18f90 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e  gn key actions].
18fa0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
18fb0 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
18fc0 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
18fd0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
18fe0 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  t [REPLACE] cons
18ff0 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72  traints,.** do r
19000 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
19010 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72  T processing, or
19020 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72   [DROP TABLE] pr
19030 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a  ocessing.  The.*
19040 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  * count does not
19050 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66   include rows of
19060 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65   views that fire
19070 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
19080 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f  trigger],.** tho
19090 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45  ugh if the INSTE
190a0 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61  AD OF trigger ma
190b0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69  kes changes of i
190c0 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68  ts own, those ch
190d0 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f  anges .** are co
190e0 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65  unted.)^.** ^The
190f0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
19100 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
19110 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61  n counts the cha
19120 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a  nges as soon as.
19130 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
19140 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
19150 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
19160 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
19170 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70  t handle.** is p
19180 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
19190 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
191a0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
191b0 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
191c0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
191d0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
191e0 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
191f0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
19200 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
19210 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
19220 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
19230 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
19240 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
19250 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
19260 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
19270 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
19280 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
19290 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
192a0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
192b0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
192c0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
192d0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
192e0 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
192f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
19300 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
19310 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
19320 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
19330 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
19340 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
19350 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
19360 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
19370 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
19380 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
19390 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
193a0 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
193b0 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
193c0 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
193d0 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
193e0 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
193f0 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
19400 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
19410 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
19420 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
19430 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
19440 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
19450 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
19460 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
19470 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
19480 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
19490 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
194a0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
194b0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
194c0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
194d0 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
194e0 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
194f0 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
19500 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
19510 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
19520 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
19530 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
19540 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
19550 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
19560 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
19570 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
19580 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
19590 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
195a0 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
195b0 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
195c0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
195d0 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
195e0 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
195f0 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
19600 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
19610 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
19620 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
19630 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
19640 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
19650 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
19660 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
19670 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
19680 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
19690 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
196a0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
196b0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
196c0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
196d0 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
196e0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
196f0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
19700 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
19710 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
19720 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
19730 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
19740 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
19750 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
19760 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
19770 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
19780 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
19790 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
197a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
197b0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
197c0 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
197d0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
197e0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
197f0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
19800 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
19810 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
19820 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
19830 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
19840 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
19850 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
19860 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
19870 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
19880 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
19890 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
198a0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
198b0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
198c0 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
198d0 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
198e0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
198f0 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
19900 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
19910 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
19920 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
19930 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
19940 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
19950 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
19960 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
19970 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
19980 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
19990 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
199a0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
199b0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
199c0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
199d0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
199e0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
199f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
19a00 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
19a10 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
19a20 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
19a30 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
19a40 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
19a50 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53  ely happen..*/.S
19a60 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
19a70 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
19a80 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
19a90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
19aa0 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
19ab0 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
19ac0 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
19ad0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
19ae0 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
19af0 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
19b00 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
19b10 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
19b20 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
19b30 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
19b40 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
19b50 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
19b60 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
19b70 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
19b80 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
19b90 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
19ba0 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
19bb0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
19bc0 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
19bd0 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
19be0 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
19bf0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
19c00 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
19c10 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
19c20 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
19c30 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
19c40 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
19c50 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
19c60 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
19c70 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
19c80 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
19c90 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
19ca0 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
19cb0 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
19cc0 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
19cd0 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
19ce0 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
19cf0 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
19d00 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
19d10 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
19d20 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
19d30 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
19d40 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
19d50 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
19d60 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
19d70 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
19d80 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
19d90 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
19da0 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
19db0 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
19dc0 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
19dd0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
19de0 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
19df0 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
19e00 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
19e10 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
19e20 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
19e30 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
19e40 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
19e50 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
19e60 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
19e70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
19e80 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
19e90 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
19ea0 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
19eb0 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
19ec0 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
19ed0 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
19ee0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
19ef0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
19f00 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
19f10 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
19f20 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
19f30 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
19f40 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
19f50 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
19f60 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
19f70 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
19f80 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
19f90 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
19fa0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
19fb0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
19fc0 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
19fd0 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
19fe0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
19ff0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
1a000 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
1a010 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
1a020 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1a030 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
1a040 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
1a050 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1a060 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
1a070 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
1a080 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1a090 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1a0a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1a0b0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
1a0c0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
1a0d0 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  der..*/.SQLITE_A
1a0e0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
1a0f0 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
1a100 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45  ar *sql);.SQLITE
1a110 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1a120 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
1a130 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
1a140 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1a150 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
1a160 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
1a170 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
1a180 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1a190 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
1a1a0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
1a1b0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
1a1c0 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
1a1d0 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
1a1e0 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
1a1f0 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
1a200 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
1a210 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
1a220 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
1a230 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1a240 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
1a250 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
1a260 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
1a270 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
1a280 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1a290 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
1a2a0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
1a2b0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
1a2c0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
1a2d0 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
1a2e0 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
1a2f0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
1a300 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
1a310 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1a320 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1a330 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1a340 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
1a350 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
1a360 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
1a370 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
1a380 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1a390 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
1a3a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
1a3b0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1a3c0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
1a3d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
1a3e0 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
1a3f0 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
1a400 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
1a410 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
1a420 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
1a430 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
1a440 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
1a450 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
1a460 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
1a470 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
1a480 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
1a490 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
1a4a0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
1a4b0 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
1a4c0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
1a4d0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1a4e0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
1a4f0 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
1a500 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
1a510 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
1a520 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
1a530 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
1a540 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
1a550 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
1a560 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
1a570 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
1a580 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
1a590 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
1a5a0 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
1a5b0 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
1a5c0 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
1a5d0 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
1a5e0 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
1a5f0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
1a600 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
1a610 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
1a620 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
1a630 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
1a640 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
1a650 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
1a660 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
1a670 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
1a680 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
1a690 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
1a6a0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
1a6b0 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
1a6c0 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
1a6d0 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
1a6e0 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
1a6f0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
1a700 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
1a710 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
1a720 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
1a730 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
1a740 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
1a750 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
1a760 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
1a770 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
1a780 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1a790 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
1a7a0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1a7b0 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
1a7c0 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
1a7d0 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
1a7e0 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
1a7f0 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
1a800 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
1a810 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
1a820 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
1a830 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
1a840 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
1a850 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
1a860 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
1a870 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
1a880 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
1a890 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
1a8a0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
1a8b0 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
1a8c0 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
1a8d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1a8e0 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
1a8f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1a900 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
1a910 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
1a920 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
1a930 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
1a940 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
1a950 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
1a960 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
1a970 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
1a980 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
1a990 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
1a9a0 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
1a9b0 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
1a9c0 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
1a9d0 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
1a9e0 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
1a9f0 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
1aa00 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
1aa10 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
1aa20 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
1aa30 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
1aa40 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
1aa50 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
1aa60 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
1aa70 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
1aa80 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
1aa90 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
1aaa0 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
1aab0 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
1aac0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
1aad0 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
1aae0 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
1aaf0 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
1ab00 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
1ab10 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
1ab20 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
1ab30 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
1ab40 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
1ab50 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
1ab60 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
1ab70 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
1ab80 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
1ab90 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
1aba0 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
1abb0 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
1abc0 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
1abd0 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
1abe0 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
1abf0 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
1ac00 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
1ac10 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
1ac20 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
1ac30 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
1ac40 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
1ac50 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
1ac60 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
1ac70 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
1ac80 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1ac90 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1aca0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1acb0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1acc0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1acd0 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1ace0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1acf0 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1ad00 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1ad10 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1ad20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1ad30 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1ad40 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
1ad50 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
1ad60 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
1ad70 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
1ad80 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
1ad90 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
1ada0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
1adb0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
1adc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1add0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1ade0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1adf0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
1ae00 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
1ae10 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
1ae20 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
1ae30 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
1ae40 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
1ae50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ae60 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
1ae70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1ae80 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1ae90 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53  sy handler..*/.S
1aea0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1aeb0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1aec0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
1aed0 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
1aee0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1aef0 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
1af00 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a  usy Timeout.**.*
1af10 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1af20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
1af30 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
1af40 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
1af50 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
1af60 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
1af70 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
1af80 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
1af90 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
1afa0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
1afb0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
1afc0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
1afd0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1afe0 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
1aff0 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
1b000 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
1b010 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1b020 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
1b030 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
1b040 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
1b050 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
1b060 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
1b070 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
1b080 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
1b090 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
1b0a0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
1b0b0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
1b0c0 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
1b0d0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
1b0e0 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
1b0f0 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
1b100 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
1b110 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1b120 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1b130 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
1b140 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1b150 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1b160 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  ny any given mom
1b170 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
1b180 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
1b190 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
1b1a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
1b1b0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
1b1c0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
1b1d0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
1b1e0 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
1b1f0 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
1b200 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  red.)^.*/.SQLITE
1b210 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1b220 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
1b230 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
1b240 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b250 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
1b260 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
1b270 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
1b280 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
1b290 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1b2a0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
1b2b0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1b2c0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
1b2d0 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
1b2e0 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
1b2f0 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
1b300 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
1b310 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
1b320 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
1b330 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
1b340 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
1b350 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1b360 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
1b370 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
1b380 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
1b390 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
1b3a0 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
1b3b0 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
1b3c0 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
1b3d0 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
1b3e0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
1b3f0 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
1b400 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
1b410 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
1b420 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1b430 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
1b440 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
1b450 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
1b460 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
1b470 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1b480 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
1b490 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1b4a0 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
1b4b0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
1b4c0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
1b4d0 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
1b4e0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1b4f0 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
1b500 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
1b510 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
1b520 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1b530 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1b540 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1b550 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1b560 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1b570 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1b580 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1b590 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1b5a0 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1b5b0 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1b5c0 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1b5d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1b5e0 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1b5f0 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1b600 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1b610 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1b620 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1b630 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1b640 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1b650 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1b660 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1b670 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1b680 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1b690 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1b6a0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1b6b0 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1b6c0 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1b6d0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1b6e0 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1b6f0 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1b700 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1b710 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1b720 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1b730 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1b740 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1b750 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1b760 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1b770 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1b780 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1b790 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b7a0 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1b7b0 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1b7c0 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1b7d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1b7e0 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1b7f0 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1b800 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1b810 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1b820 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1b830 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1b840 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1b850 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1b860 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1b870 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1b880 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1b890 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1b8a0 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1b8b0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1b8c0 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1b8d0 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1b8e0 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1b8f0 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1b900 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1b910 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1b920 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
1b930 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1b940 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1b950 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1b960 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1b970 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1b980 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1b990 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b9a0 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1b9b0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1b9c0 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1b9d0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b9e0 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1b9f0 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1ba00 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1ba10 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1ba20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1ba30 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1ba40 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1ba50 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1ba60 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1ba70 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1ba80 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1ba90 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1baa0 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1bab0 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1bac0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1bad0 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1bae0 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1baf0 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1bb00 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1bb10 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1bb20 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1bb30 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1bb40 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1bb50 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1bb60 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1bb70 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1bb80 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1bb90 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1bba0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1bbb0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1bbc0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1bbd0 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1bbe0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1bbf0 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1bc00 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1bc10 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1bc20 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1bc30 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1bc40 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1bc50 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1bc60 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1bc70 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1bc80 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1bc90 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1bca0 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1bcb0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1bcc0 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1bcd0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1bce0 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1bcf0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1bd00 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1bd10 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1bd20 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1bd30 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1bd40 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1bd50 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1bd60 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1bd70 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1bd80 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1bd90 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1bda0 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1bdb0 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1bdc0 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1bdd0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1bde0 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1bdf0 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1be00 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1be10 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1be20 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1be30 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1be40 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1be50 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1be60 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1be70 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1be80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1be90 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1bea0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1beb0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1bec0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
1bed0 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1bee0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1bef0 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1bf00 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1bf10 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1bf20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1bf30 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1bf40 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1bf50 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1bf60 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1bf70 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1bf80 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1bf90 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1bfa0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1bfb0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1bfc0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1bfd0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1bfe0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1bff0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1c000 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1c010 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1c020 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
1c030 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  I void sqlite3_f
1c040 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1c050 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1c060 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1c070 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1c080 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1c090 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1c0a0 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1c0b0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1c0c0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1c0d0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1c0e0 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1c0f0 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
1c100 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1c110 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1c120 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1c130 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1c140 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1c150 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1c160 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1c170 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1c180 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1c190 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1c1a0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1c1b0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1c1c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1c1d0 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1c1e0 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1c1f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1c200 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1c210 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1c220 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1c230 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1c240 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1c250 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1c260 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1c270 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1c280 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1c290 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1c2a0 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1c2b0 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1c2c0 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1c2d0 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1c2e0 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1c2f0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1c300 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1c310 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1c320 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1c330 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1c340 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1c350 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1c360 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1c370 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1c380 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1c390 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1c3a0 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1c3b0 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1c3c0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1c3d0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1c3e0 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1c3f0 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1c400 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1c410 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1c420 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1c430 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1c440 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1c450 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1c460 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1c470 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1c480 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1c490 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1c4a0 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1c4b0 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1c4c0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1c4d0 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1c4e0 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1c4f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1c500 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1c510 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1c520 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1c530 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1c540 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1c550 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1c560 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1c570 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1c580 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1c590 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1c5a0 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1c5b0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1c5c0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1c5d0 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1c5e0 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1c5f0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1c600 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1c610 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1c620 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1c630 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1c640 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1c650 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1c660 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1c670 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1c680 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c690 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1c6a0 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1c6b0 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1c6c0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1c6d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1c6e0 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1c6f0 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1c700 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1c710 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1c720 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1c730 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1c740 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1c750 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1c760 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1c770 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1c780 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1c790 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1c7a0 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
1c7b0 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1c7c0 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1c7d0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1c7e0 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1c7f0 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
1c800 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1c810 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
1c820 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
1c830 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
1c840 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
1c850 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
1c860 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
1c870 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
1c880 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
1c890 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
1c8a0 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
1c8b0 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
1c8c0 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
1c8d0 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
1c8e0 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
1c8f0 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
1c900 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
1c910 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
1c920 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
1c930 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
1c940 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1c950 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c960 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
1c970 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
1c980 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
1c990 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1c9a0 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
1c9b0 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
1c9c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
1c9d0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1c9e0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1c9f0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1ca00 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1ca10 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1ca20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
1ca30 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
1ca40 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1ca50 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1ca60 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1ca70 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1ca80 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1ca90 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1caa0 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
1cab0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
1cac0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
1cad0 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
1cae0 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
1caf0 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
1cb00 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1cb10 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1cb20 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1cb30 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1cb40 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
1cb50 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
1cb60 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1cb70 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
1cb80 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
1cb90 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
1cba0 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
1cbb0 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
1cbc0 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
1cbd0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
1cbe0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1cbf0 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1cc00 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1cc10 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1cc20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1cc30 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1cc40 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
1cc50 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
1cc60 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
1cc70 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
1cc80 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
1cc90 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
1cca0 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
1ccb0 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
1ccc0 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
1ccd0 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
1cce0 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
1ccf0 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
1cd00 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
1cd10 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
1cd20 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
1cd30 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
1cd40 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
1cd50 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
1cd60 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
1cd70 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
1cd80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
1cd90 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
1cda0 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
1cdb0 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
1cdc0 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
1cdd0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
1cde0 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
1cdf0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1ce00 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1ce10 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1ce20 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1ce30 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1ce40 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
1ce50 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1ce60 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1ce70 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1ce80 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1ce90 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1cea0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
1ceb0 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
1cec0 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
1ced0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
1cee0 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
1cef0 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
1cf00 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
1cf10 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1cf20 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1cf30 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1cf40 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1cf50 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1cf60 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1cf70 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1cf80 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1cf90 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1cfa0 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1cfb0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1cfc0 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1cfd0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1cfe0 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
1cff0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d   char *sqlite3_m
1d000 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1d010 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f  r*,...);.SQLITE_
1d020 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
1d030 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
1d040 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1d050 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1d060 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
1d070 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1d080 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
1d090 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1d0a0 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69   *sqlite3_vsnpri
1d0b0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1d0c0 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1d0d0 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  st);../*.** CAPI
1d0e0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1d0f0 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
1d100 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
1d110 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
1d120 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
1d130 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
1d140 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
1d150 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1d160 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
1d170 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1d180 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
1d190 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
1d1a0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
1d1b0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
1d1c0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
1d1d0 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
1d1e0 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
1d1f0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1d200 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
1d210 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
1d220 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d230 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1d240 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1d250 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
1d260 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
1d270 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
1d280 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
1d290 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
1d2a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d2b0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
1d2c0 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
1d2d0 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
1d2e0 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
1d2f0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
1d300 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
1d310 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
1d320 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
1d330 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
1d340 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d350 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
1d360 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1d370 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
1d380 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
1d390 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
1d3a0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
1d3b0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1d3c0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1d3d0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
1d3e0 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
1d3f0 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
1d400 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
1d410 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
1d420 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
1d430 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
1d440 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1d450 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
1d460 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
1d470 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
1d480 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
1d490 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
1d4a0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
1d4b0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
1d4c0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
1d4d0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
1d4e0 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
1d4f0 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
1d500 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
1d510 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1d520 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
1d530 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
1d540 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
1d550 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1d560 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
1d570 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
1d580 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
1d590 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1d5a0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1d5b0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
1d5c0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
1d5d0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1d5e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1d5f0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1d600 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  oc()..**.** ^(Th
1d610 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1d620 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
1d630 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
1d640 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
1d650 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
1d660 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
1d670 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
1d680 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
1d690 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
1d6a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d6b0 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
1d6c0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
1d6d0 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66  arameter.)^ ^ If
1d6e0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1d6f0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1d700 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
1d710 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1d720 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1d730 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1d740 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1d750 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
1d760 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
1d770 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1d780 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d790 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  ()..** ^If the s
1d7a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1d7b0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1d7c0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
1d7d0 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1d7e0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1d7f0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1d800 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1d810 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
1d820 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
1d830 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1d840 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1d850 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  c()..** ^sqlite3
1d860 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1d870 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1d880 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1d890 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1d8a0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1d8b0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
1d8c0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
1d8d0 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
1d8e0 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1d8f0 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1d900 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1d910 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1d920 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1d930 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
1d940 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
1d950 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
1d960 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
1d970 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
1d980 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
1d990 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1d9a0 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
1d9b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d9c0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
1d9d0 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
1d9e0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
1d9f0 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
1da00 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1da10 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1da20 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
1da30 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
1da40 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1da50 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1da60 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1da70 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1da80 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1da90 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1daa0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1dab0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1dac0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1dad0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1dae0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1daf0 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1db00 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1db10 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1db20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1db30 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1db40 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1db50 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1db60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1db70 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1db80 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1db90 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1dba0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1dbb0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1dbc0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1dbd0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1dbe0 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1dbf0 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1dc00 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1dc10 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1dc20 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1dc30 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1dc40 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1dc50 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1dc60 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1dc70 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1dc80 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1dc90 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1dca0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1dcb0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1dcc0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1dcd0 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1dce0 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1dcf0 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1dd00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1dd10 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1dd20 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1dd30 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1dd40 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1dd50 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1dd60 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1dd70 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1dd80 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1dd90 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1dda0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1ddb0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1ddc0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ddd0 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1dde0 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1ddf0 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1de00 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1de10 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1de20 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1de30 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1de40 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1de50 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1de60 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1de70 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1de80 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1de90 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1dea0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1deb0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1dec0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1ded0 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1dee0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1def0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1df00 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  alloc()]..*/.SQL
1df10 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
1df20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1df30 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1df40 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1df50 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1df60 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1df70 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
1df80 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1df90 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1dfa0 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
1dfb0 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  cs.**.** SQLite 
1dfc0 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
1dfd0 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
1dfe0 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
1dff0 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
1e000 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
1e010 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
1e020 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
1e030 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1e040 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
1e050 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
1e060 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1e070 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
1e080 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  em..**.** ^The [
1e090 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1e0a0 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
1e0b0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1e0c0 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66  r of bytes.** of
1e0d0 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
1e0e0 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
1e0f0 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
1e100 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20  freed)..** ^The 
1e110 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1e120 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
1e130 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1e140 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75   maximum.** valu
1e150 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
1e160 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
1e170 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
1e180 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61  r mark.** was la
1e190 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20  st reset.  ^The 
1e1a0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
1e1b0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1e1c0 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a  ry_used()] and.*
1e1d0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1e1e0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1e1f0 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
1e200 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20  ead.** added by 
1e210 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
1e220 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1e230 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1e240 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f  )],.** but not o
1e250 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
1e260 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79   the any underly
1e270 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61  ing system libra
1e280 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  ry.** routines t
1e290 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
1e2a0 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
1e2b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1e2c0 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  ry high-water ma
1e2d0 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
1e2e0 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
1e2f0 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
1e300 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
1e310 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
1e320 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
1e330 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1e340 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1e350 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61  s true.  ^The va
1e360 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
1e370 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1e380 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
1e390 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
1e3a0 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72  er mark.** prior
1e3b0 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
1e3c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
1e3d0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1e3e0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
1e3f0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
1e400 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
1e410 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1e420 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
1e430 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
1e440 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
1e450 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
1e460 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
1e470 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
1e480 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
1e490 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
1e4a0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
1e4b0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
1e4c0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
1e4d0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
1e4e0 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
1e4f0 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
1e500 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
1e510 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
1e520 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
1e530 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
1e540 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
1e550 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
1e560 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
1e570 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
1e580 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
1e590 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
1e5a0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
1e5b0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
1e5c0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
1e5d0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
1e5e0 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
1e5f0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
1e600 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
1e610 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
1e620 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 49 66 20  uffer P..** ^If 
1e630 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
1e640 6e 65 2c 20 74 68 65 6e 20 50 20 63 61 6e 20 62  ne, then P can b
1e650 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
1e660 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73  ..**.** ^If this
1e670 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74   routine has not
1e680 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79   been previously
1e690 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68   called or if th
1e6a0 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61  e previous.** ca
1e6b0 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68  ll had N less th
1e6c0 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 74 68 65  an one, then the
1e6d0 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
1e6e0 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1e6f0 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  .** obtained fro
1e700 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
1e710 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
1e720 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1e730 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1e740 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
1e750 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
1e760 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
1e770 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 74 68 65  of 1 or more the
1e780 6e 0a 2a 2a 20 74 68 65 20 70 73 65 75 64 6f 2d  n.** the pseudo-
1e790 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
1e7a0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
1e7b0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
1e7c0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
1e7d0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
1e7e0 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
1e7f0 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ethod..*/.SQLITE
1e800 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
1e810 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
1e820 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
1e830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1e840 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
1e850 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
1e860 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  cks.**.** ^This 
1e870 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
1e880 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  s an authorizer 
1e890 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
1e8a0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1e8b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e8c0 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
1e8d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
1e8e0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
1e8f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e900 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
1e910 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
1e920 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
1e930 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1e940 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1e950 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
1e960 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1e970 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
1e980 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
1e990 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e9a0 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76  16_v2()].  ^At v
1e9b0 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
1e9c0 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
1e9d0 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
1e9e0 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
1e9f0 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
1ea00 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
1ea10 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
1ea20 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ea30 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
1ea40 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
1ea50 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
1ea60 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
1ea70 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
1ea80 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
1ea90 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
1eaa0 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
1eab0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1eac0 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
1ead0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
1eae0 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
1eaf0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1eb00 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
1eb10 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
1eb20 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
1eb30 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
1eb40 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
1eb50 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
1eb60 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
1eb70 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
1eb80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1eb90 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
1eba0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
1ebb0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
1ebc0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
1ebd0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
1ebe0 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
1ebf0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1ec00 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1ec10 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1ec20 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
1ec30 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1ec40 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1ec50 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
1ec60 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
1ec70 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
1ec80 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
1ec90 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
1eca0 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
1ecb0 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
1ecc0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1ecd0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
1ece0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1ecf0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1ed00 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1ed10 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
1ed20 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
1ed30 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1ed40 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
1ed50 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
1ed60 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
1ed70 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
1ed80 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1ed90 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1eda0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
1edb0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
1edc0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
1edd0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
1ede0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
1edf0 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
1ee00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
1ee10 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1ee20 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1ee30 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
1ee40 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
1ee50 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
1ee60 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
1ee70 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1ee80 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
1ee90 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
1eea0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
1eeb0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
1eec0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1eed0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
1eee0 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
1eef0 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
1ef00 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
1ef10 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
1ef20 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
1ef30 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1ef40 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
1ef50 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1ef60 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
1ef70 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
1ef80 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
1ef90 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
1efa0 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
1efb0 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
1efc0 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
1efd0 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
1efe0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
1eff0 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
1f000 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
1f010 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
1f020 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
1f030 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
1f040 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
1f050 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
1f060 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
1f070 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
1f080 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
1f090 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49  f a table..** ^I
1f0a0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1f0b0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
1f0c0 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
1f0d0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1f0e0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1f0f0 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
1f100 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
1f110 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
1f120 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
1f130 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
1f140 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
1f150 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
1f160 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
1f170 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
1f180 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
1f190 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1f1a0 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
1f1b0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
1f1c0 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
1f1d0 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
1f1e0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
1f1f0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
1f200 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
1f210 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
1f220 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
1f230 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
1f240 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
1f250 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
1f260 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
1f270 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
1f280 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
1f290 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
1f2a0 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
1f2b0 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
1f2c0 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
1f2d0 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
1f2e0 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
1f2f0 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
1f300 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1f310 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
1f320 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
1f330 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
1f340 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
1f350 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
1f360 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
1f370 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
1f380 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
1f390 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
1f3a0 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
1f3b0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1f3c0 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
1f3d0 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
1f3e0 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
1f3f0 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
1f400 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
1f410 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1f420 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
1f430 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
1f440 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
1f450 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
1f460 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
1f470 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
1f480 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1f490 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
1f4a0 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
1f4b0 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
1f4c0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
1f4d0 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
1f4e0 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
1f4f0 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
1f500 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
1f510 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
1f520 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
1f530 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
1f540 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
1f550 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
1f560 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
1f570 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
1f580 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
1f590 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
1f5a0 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
1f5b0 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
1f5c0 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
1f5d0 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
1f5e0 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
1f5f0 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
1f600 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1f610 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1f620 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1f630 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1f640 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1f650 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1f660 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
1f670 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f680 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
1f690 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f6a0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
1f6b0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
1f6c0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
1f6d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f6e0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
1f6f0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
1f700 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
1f710 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
1f720 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f730 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
1f740 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
1f750 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
1f760 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
1f770 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
1f780 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1f790 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
1f7a0 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
1f7b0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
1f7c0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
1f7d0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
1f7e0 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
1f7f0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1f800 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
1f810 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
1f820 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
1f830 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
1f840 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1f850 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1f860 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
1f870 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f880 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1f890 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
1f8a0 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
1f8b0 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
1f8c0 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
1f8d0 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
1f8e0 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
1f8f0 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
1f900 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
1f910 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
1f920 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
1f930 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
1f940 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
1f950 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
1f960 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
1f970 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  hange..*/.SQLITE
1f980 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1f990 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1f9a0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
1f9b0 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
1f9c0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
1f9d0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1f9e0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1f9f0 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
1fa00 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
1fa10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1fa20 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
1fa30 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1fa40 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1fa50 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1fa60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
1fa70 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
1fa80 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
1fa90 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
1faa0 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
1fab0 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
1fac0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
1fad0 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
1fae0 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
1faf0 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
1fb00 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
1fb10 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1fb20 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
1fb30 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
1fb40 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1fb50 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1fb60 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
1fb70 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
1fb80 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c  o used as a [SQL
1fb90 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  ITE_ROLLBACK | r
1fba0 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66  eturn code].** f
1fbb0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
1fbc0 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
1fbd0 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
1fbe0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fbf0 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
1fc00 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
1fc10 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
1fc20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
1fc30 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
1fc40 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
1fc50 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
1fc60 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
1fc70 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
1fc80 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1fc90 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
1fca0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1fcb0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1fcc0 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
1fcd0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
1fce0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
1fcf0 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
1fd00 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
1fd10 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
1fd20 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
1fd30 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1fd40 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1fd50 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1fd60 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
1fd70 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
1fd80 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
1fd90 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1fda0 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
1fdb0 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
1fdc0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
1fdd0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1fde0 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
1fdf0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
1fe00 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
1fe10 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
1fe20 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
1fe30 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
1fe40 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
1fe50 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1fe60 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
1fe70 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
1fe80 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
1fe90 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
1fea0 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
1feb0 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
1fec0 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
1fed0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
1fee0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
1fef0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
1ff00 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
1ff10 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1ff20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1ff30 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
1ff40 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
1ff50 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
1ff60 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
1ff70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1ff80 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ff90 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
1ffa0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
1ffb0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1ffc0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1ffd0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1ffe0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
1fff0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
20000 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
20010 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
20020 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
20030 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
20040 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20050 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20060 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
20070 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
20080 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
20090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
200a0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
200b0 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
200c0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
200d0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
200e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
200f0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
20100 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
20110 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
20120 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20130 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
20140 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
20150 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
20160 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
20170 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
20180 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
20190 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
201a0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
201b0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
201c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
201d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
201e0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
201f0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
20200 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
20210 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20220 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
20230 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
20240 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
20250 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20260 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20270 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
20280 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
20290 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
202a0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
202b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
202c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
202d0 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
202e0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
202f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20300 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20310 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
20320 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
20330 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20340 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20350 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20360 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
20370 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
20380 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
20390 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
203a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
203b0 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
203c0 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
203d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
203e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
203f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20400 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
20410 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
20420 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
20430 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
20440 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20450 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
20460 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
20470 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
20480 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20490 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
204a0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
204b0 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
204c0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
204d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
204e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
204f0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
20500 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
20510 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
20520 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20530 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
20540 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
20550 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
20560 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
20570 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
20580 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
20590 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
205a0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
205b0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
205c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
205d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
205e0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
205f0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
20600 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
20610 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20620 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
20630 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
20640 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
20650 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
20660 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
20670 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
20680 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
20690 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
206a0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
206b0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
206c0 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
206d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
206e0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
206f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
20700 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20710 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
20720 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
20730 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
20740 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20750 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20760 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
20770 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
20780 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
20790 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
207a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
207b0 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
207c0 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
207d0 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
207e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
207f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20800 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
20810 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
20820 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
20830 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20840 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20850 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
20860 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
20870 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
20880 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20890 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
208a0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
208b0 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
208c0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
208d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
208e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
208f0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
20900 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
20910 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
20920 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20930 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20940 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
20950 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
20960 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
20970 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
20980 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20990 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
209a0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
209b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
209c0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
209d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
209e0 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
209f0 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
20a00 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
20a10 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
20a20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
20a30 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
20a40 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
20a50 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
20a60 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
20a70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
20a80 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
20a90 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
20aa0 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
20ab0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52  ine SQLITE_RECUR
20ac0 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SIVE            
20ad0 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  33   /* NULL    
20ae0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
20af0 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a          */../*.*
20b00 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
20b10 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
20b20 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
20b30 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
20b40 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
20b50 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
20b60 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
20b70 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
20b80 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
20b90 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
20ba0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
20bb0 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
20bc0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
20bd0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
20be0 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
20bf0 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
20c00 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
20c10 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
20c20 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
20c30 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
20c40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
20c50 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
20c60 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
20c70 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
20c80 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
20c90 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
20ca0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
20cb0 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
20cc0 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
20cd0 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
20ce0 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
20cf0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
20d00 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
20d10 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
20d20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
20d30 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
20d40 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
20d50 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
20d60 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
20d70 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
20d80 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  )^.**.** The [SQ
20d90 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f  LITE_TRACE_SIZE_
20da0 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  LIMIT] compile-t
20db0 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  ime option can b
20dc0 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a  e used to limit.
20dd0 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  ** the length of
20de0 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65   [bound paramete
20df0 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20  r] expansion in 
20e00 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71  the output of sq
20e10 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a  lite3_trace()..*
20e20 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
20e30 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
20e40 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
20e50 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
20e60 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
20e70 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
20e80 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20  finishes.  ^The 
20e90 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
20ea0 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
20eb0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
20ec0 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
20ed0 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
20ee0 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
20ef0 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
20f00 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
20f10 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f  o run.  ^The pro
20f20 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  file callback.**
20f30 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74   time is in unit
20f40 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73  s of nanoseconds
20f50 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75  , however the cu
20f60 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
20f70 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20  tion.** is only 
20f80 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69  capable of milli
20f90 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f  second resolutio
20fa0 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61  n so the six lea
20fb0 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a  st significant.*
20fc0 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20  * digits in the 
20fd0 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67  time are meaning
20fe0 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65  less.  Future ve
20ff0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
21000 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64  .** might provid
21010 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75  e greater resolu
21020 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66  tion on the prof
21030 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20  iler callback.  
21040 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
21050 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f  rofile() functio
21060 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  n is considered 
21070 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
21080 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74   is.** subject t
21090 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  o change in futu
210a0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
210b0 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  QLite..*/.SQLITE
210c0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
210d0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
210e0 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
210f0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
21100 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
21110 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45  ITE_API SQLITE_E
21120 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
21130 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
21140 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
21150 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
21160 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
21170 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
21180 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
21190 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
211a0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
211b0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
211c0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
211d0 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
211e0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
211f0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
21200 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
21210 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
21220 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
21230 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
21240 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
21250 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
21260 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
21270 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
21280 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
21290 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
212a0 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
212b0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
212c0 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
212d0 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
212e0 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
212f0 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
21300 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
21310 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
21320 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
21330 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
21340 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
21350 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
21360 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
21370 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62  approximate numb
21380 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
21390 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
213a0 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
213b0 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
213c0 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
213d0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
213e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
213f0 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20    ^If N is less 
21400 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68  than one then th
21410 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61  e progress.** ha
21420 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65  ndler is disable
21430 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  d..**.** ^Only a
21440 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
21450 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
21460 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
21470 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
21480 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
21490 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
214a0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
214b0 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
214c0 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
214d0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
214e0 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
214f0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
21500 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
21510 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
21520 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
21530 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
21540 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
21550 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
21560 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
21570 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
21580 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
21590 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
215a0 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
215b0 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
215c0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
215d0 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
215e0 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
215f0 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
21600 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
21610 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
21620 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
21630 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
21640 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
21650 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
21660 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
21670 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
21680 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
21690 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
216a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
216b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
216c0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
216d0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
216e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
216f0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
21700 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
21710 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
21720 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  *.*/.SQLITE_API 
21730 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
21740 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
21750 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
21760 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
21770 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
21780 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
21790 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
217a0 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
217b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
217c0 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
217d0 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
217e0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
217f0 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
21800 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
21810 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
21820 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
21830 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
21840 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
21850 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
21860 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
21870 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
21880 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
21890 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
218a0 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
218b0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
218c0 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
218d0 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
218e0 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
218f0 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
21900 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
21910 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
21920 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
21930 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
21940 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
21950 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
21960 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
21970 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
21980 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
21990 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
219a0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
219b0 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
219c0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
219d0 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
219e0 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
219f0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
21a00 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
21a10 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
21a20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
21a30 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
21a40 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
21a50 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
21a60 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
21a70 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
21a80 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
21a90 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
21aa0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
21ab0 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
21ac0 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
21ad0 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
21ae0 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
21af0 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
21b00 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
21b10 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
21b20 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
21b30 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71  e UTF-8 if.** sq
21b40 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
21b50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21b60 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ) is called and.
21b70 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  ** UTF-16 in the
21b80 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
21b90 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70  er if sqlite3_op
21ba0 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a  en16() is used..
21bb0 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
21bc0 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
21bd0 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
21be0 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
21bf0 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
21c00 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
21c10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
21c20 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
21c30 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
21c40 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
21c50 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
21c60 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
21c70 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
21c80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
21c90 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
21ca0 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
21cb0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
21cc0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
21cd0 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
21ce0 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
21cf0 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
21d00 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
21d10 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
21d20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
21d30 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
21d40 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
21d50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
21d60 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
21d70 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
21d80 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
21d90 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
21da0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
21db0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
21dc0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
21dd0 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
21de0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
21df0 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
21e00 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
21e10 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
21e20 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
21e30 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
21e40 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
21e50 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
21e60 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
21e70 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
21e80 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
21e90 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
21ea0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
21eb0 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
21ec0 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
21ed0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
21ee0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
21ef0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
21f00 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
21f10 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
21f20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
21f30 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
21f40 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
21f50 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
21f60 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
21f70 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
21f80 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
21f90 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
21fa0 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
21fb0 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
21fc0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
21fd0 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
21fe0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
21ff0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
22000 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
22010 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
22020 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
22030 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
22040 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
22050 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
22060 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
22070 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
22080 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
22090 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
220a0 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
220b0 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
220c0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
220d0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
220e0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
220f0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
22100 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
22110 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
22120 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22130 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
22140 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
22150 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
22160 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
22170 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
22180 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
22190 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
221a0 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
221b0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
221c0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
221d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
221e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
221f0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
22200 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
22210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
22220 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
22230 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
22240 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
22250 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
22260 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
22270 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
22280 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
22290 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
222a0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
222b0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
222c0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
222d0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
222e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
222f0 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
22300 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
22310 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
22320 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
22330 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
22340 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
22350 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
22360 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
22370 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
22380 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
22390 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
223a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
223b0 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
223c0 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
223d0 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
223e0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
223f0 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
22400 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
22410 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
22420 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
22430 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
22440 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
22450 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
22460 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
22470 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22480 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
22490 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
224a0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
224b0 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
224c0 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
224d0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
224e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
224f0 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
22500 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
22510 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
22520 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
22530 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
22540 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
22550 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
22560 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22570 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
22580 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
22590 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
225a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
225b0 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
225c0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
225d0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
225e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
225f0 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
22600 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
22610 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
22620 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
22630 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
22640 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
22650 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
22660 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
22670 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
22680 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
22690 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
226a0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
226b0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
226c0 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
226d0 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
226e0 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
226f0 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
22700 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
22710 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
22720 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
22730 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
22740 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
22750 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
22760 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
22770 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
22780 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
22790 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
227a0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
227b0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
227c0 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
227d0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
227e0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
227f0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
22800 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
22810 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
22820 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
22830 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
22840 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
22850 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
22860 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
22870 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
22880 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
22890 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
228a0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
228b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
228c0 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
228d0 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
228e0 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
228f0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
22900 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
22910 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
22920 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
22930 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
22940 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
22950 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
22960 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
22970 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
22980 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
22990 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
229a0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
229b0 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
229c0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
229d0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
229e0 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
229f0 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
22a00 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
22a10 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
22a20 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
22a30 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
22a40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
22a50 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
22a60 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
22a70 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
22a80 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
22a90 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
22aa0 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
22ab0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
22ac0 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
22ad0 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
22ae0 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
22af0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
22b00 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
22b10 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
22b20 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
22b30 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
22b40 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
22b50 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
22b60 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
22b70 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
22b80 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
22b90 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
22ba0 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
22bb0 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
22bc0 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
22bd0 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
22be0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
22bf0 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
22c00 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
22c10 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
22c20 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
22c30 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
22c40 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
22c50 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
22c60 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
22c70 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
22c80 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
22c90 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
22ca0 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
22cb0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
22cc0 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
22cd0 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
22ce0 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
22cf0 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
22d00 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
22d10 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
22d20 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
22d30 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
22d40 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
22d50 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
22d60 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
22d70 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
22d80 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
22d90 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
22da0 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
22db0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
22dc0 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
22dd0 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
22de0 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
22df0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
22e00 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
22e10 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f  h. .** ^On windo
22e20 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
22e30 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
22e40 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
22e50 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
22e60 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
22e70 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f  C:")..**.** [[co
22e80 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72  re URI query par
22e90 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65  ameters]].** The
22ea0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
22eb0 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f   of a URI may co
22ec0 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73  ntain parameters
22ed0 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70   that are interp
22ee0 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20  reted.** either 
22ef0 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66  by SQLite itself
22f00 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c  , or by a [VFS |
22f10 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c   custom VFS impl
22f20 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  ementation]..** 
22f30 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
22f40 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  s the following 
22f50 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61  three query para
22f60 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
22f70 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
22f80 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
22f90 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
22fa0 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
22fb0 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
22fc0 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
22fd0 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
22fe0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
22ff0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
23000 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
23010 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
23020 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
23030 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
23040 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
23050 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
23060 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
23070 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
23080 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
23090 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
230a0 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
230b0 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
230c0 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
230d0 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
230e0 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
230f0 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
23100 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
23110 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
23120 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
23130 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
23140 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
23150 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
23160 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
23170 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
23180 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
23190 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
231a0 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
231b0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
231c0 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
231d0 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
231e0 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
231f0 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
23200 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
23210 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
23220 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
23230 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
23240 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
23250 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
23260 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
23270 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
23280 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
23290 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
232a0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
232b0 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
232c0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
232d0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
232e0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
232f0 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
23300 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
23310 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
23320 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
23330 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
23340 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
23350 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
23360 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
23370 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
23380 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
23390 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
233a0 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
233b0 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
233c0 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
233d0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
233e0 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
233f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
23400 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
23410 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
23420 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
23430 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
23440 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
23450 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
23460 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
23470 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
23480 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
23490 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
234a0 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
234b0 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
234c0 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
234d0 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
234e0 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
234f0 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
23500 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
23510 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
23520 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
23530 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
23540 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
23550 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
23560 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
23570 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
23580 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
23590 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
235a0 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
235b0 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
235c0 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
235d0 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
235e0 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
235f0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
23600 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
23610 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
23620 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
23630 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
23640 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
23650 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
23660 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
23670 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
23680 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
23690 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
236a0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
236b0 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
236c0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
236d0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
236e0 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
236f0 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
23700 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
23710 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
23720 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
23730 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
23740 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
23750 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
23760 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
23770 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
23780 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
23790 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  lag..** </ul>.**
237a0 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
237b0 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
237c0 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
237d0 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
237e0 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
237f0 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
23800 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
23810 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
23820 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
23830 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
23840 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
23850 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
23860 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
23870 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
23880 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
23890 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
238a0 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
238b0 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
238c0 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
238d0 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
238e0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
238f0 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
23900 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
23910 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
23920 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
23930 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
23940 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
23950 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
23960 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
23970 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
23980 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
23990 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
239a0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
239b0 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
239c0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
239d0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
239e0 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
239f0 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
23a00 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
23a10 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
23a20 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
23a30 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
23a40 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
23a50 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
23a60 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
23a70 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
23a80 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
23a90 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
23aa0 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
23ab0 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
23ac0 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
23ad0 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
23ae0 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
23af0 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
23b00 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
23b10 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
23b20 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
23b30 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
23b40 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
23b50 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
23b60 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
23b70 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
23b80 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
23b90 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
23ba0 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
23bb0 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
23bc0 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
23bd0 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
23be0 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
23bf0 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
23c00 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
23c10 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
23c20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
23c30 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
23c40 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
23c50 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
23c60 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
23c70 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
23c80 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
23c90 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
23ca0 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
23cb0 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
23cc0 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
23cd0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
23ce0 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
23cf0 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
23d00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
23d10 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
23d20 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
23d30 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
23d40 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
23d50 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c  fs=unix-nolock <
23d60 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  td>.**          
23d70 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65  Open file "/home
23d80 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20  /fred/data.db". 
23d90 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20  Use the special 
23da0 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b  VFS "unix-nolock
23db0 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
23dc0 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
23dd0 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
23de0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
23df0 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
23e00 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
23e10 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
23e20 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
23e30 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
23e40 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
23e50 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
23e60 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
23e70 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
23e80 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
23e90 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
23ea0 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
23eb0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
23ec0 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
23ed0 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
23ee0 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
23ef0 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
23f00 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
23f10 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
23f20 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
23f30 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
23f40 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
23f50 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
23f60 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
23f70 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
23f80 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
23f90 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
23fa0 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
23fb0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
23fc0 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
23fd0 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
23fe0 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
23ff0 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
24000 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
24010 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
24020 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
24030 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
24040 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
24050 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
24060 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
24070 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
24080 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
24090 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
240a0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
240b0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
240c0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
240d0 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
240e0 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
240f0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
24100 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
24110 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
24120 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
24130 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
24140 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
24150 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
24160 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
24170 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
24180 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
24190 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
241a0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
241b0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
241c0 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
241d0 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
241e0 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
241f0 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
24200 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
24210 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
24220 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24230 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
24240 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
24250 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
24260 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
24270 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
24280 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
24290 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
242a0 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
242b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
242c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
242d0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
242e0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
242f0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
24300 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
24310 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
24320 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
24330 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
24340 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
24350 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
24360 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
24370 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
24380 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
24390 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
243a0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
243b0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
243c0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
243d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
243e0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
243f0 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
24400 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
24410 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
24420 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
24430 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
24440 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
24450 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
24460 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
24470 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
24480 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
24490 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
244a0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
244b0 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
244c0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
244d0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61  I3REF: Obtain Va
244e0 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72  lues For URI Par
244f0 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68  ameters.**.** Th
24500 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20  ese are utility 
24510 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c  routines, useful
24520 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e   to VFS implemen
24530 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68  tations, that ch
24540 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66  eck.** to see if
24550 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
24560 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20   was a URI that 
24570 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63  contained a spec
24580 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70  ific query .** p
24590 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66  arameter, and if
245a0 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20   so obtains the 
245b0 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75  value of that qu
245c0 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ery parameter..*
245d0 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65  *.** If F is the
245e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
245f0 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  me pointer passe
24600 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
24610 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a  () method of .**
24620 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74   a VFS implement
24630 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66  ation when the f
24640 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
24650 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e  o xOpen() has on
24660 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66  e or .** more of
24670 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
24680 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54  N_URI] or [SQLIT
24690 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20  E_OPEN_MAIN_DB] 
246a0 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20  bits set and.** 
246b0 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  P is the name of
246c0 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d   the query param
246d0 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  eter, then.** sq
246e0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
246f0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
24700 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
24710 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  e P.** parameter
24720 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72   if it exists or
24730 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
24740 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70  if P does not ap
24750 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75  pear as a .** qu
24760 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  ery parameter on
24770 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71   F.  If P is a q
24780 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
24790 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78  f F.** has no ex
247a0 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68  plicit value, th
247b0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
247c0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
247d0 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  turns.** a point
247e0 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  er to an empty s
247f0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
24800 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
24810 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
24820 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ine assumes that
24830 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a   P is a boolean.
24840 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  ** parameter and
24850 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
24860 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61  ) or false (0) a
24870 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20  ccording to the 
24880 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20  value.** of P.  
24890 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
248a0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
248b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
248c0 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a  rue (1) if the.*
248d0 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79  * value of query
248e0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
248f0 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74  one of "yes", "t
24900 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e  rue", or "on" in
24910 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20   any.** case or 
24920 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
24930 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ins with a non-z
24940 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  ero number.  The
24950 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69   .** sqlite3_uri
24960 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
24970 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73  routines returns
24980 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68   false (0) if th
24990 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75  e value of.** qu
249a0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
249b0 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20  is one of "no", 
249c0 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66  "false", or "off
249d0 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72  " in any case or
249e0 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65  .** if the value
249f0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
24a00 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66  umeric zero.  If
24a10 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72   P is not a quer
24a20 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
24a30 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61  n F or if the va
24a40 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73  lue of P is does
24a50 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f   not match any o
24a60 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20  f the.** above, 
24a70 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
24a80 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
24a90 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a  returns (B!=0)..
24aa0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
24ab0 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c  3_uri_int64(F,P,
24ac0 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65  D) routine conve
24ad0 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rts the value of
24ae0 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d   P into a.** 64-
24af0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
24b00 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
24b10 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20  hat integer, or 
24b20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a  D if P does not.
24b30 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68  ** exist.  If th
24b40 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
24b50 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
24b60 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c  than an integer,
24b70 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73   then.** zero is
24b80 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a   returned..** .*
24b90 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c  * If F is a NULL
24ba0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73   pointer, then s
24bb0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
24bc0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
24bd0 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71  s NULL and.** sq
24be0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
24bf0 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
24c00 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74   B.  If F is not
24c10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
24c20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20  and.** is not a 
24c30 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61  database file pa
24c40 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74  thname pointer t
24c50 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65  hat SQLite passe
24c60 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
24c70 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20  .** VFS method, 
24c80 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
24c90 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  r of this routin
24ca0 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  e is undefined a
24cb0 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75  nd probably.** u
24cc0 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53  ndesirable..*/.S
24cd0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
24ce0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72  char *sqlite3_ur
24cf0 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73  i_parameter(cons
24d00 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
24d10 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
24d20 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41  Param);.SQLITE_A
24d30 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75  PI int sqlite3_u
24d40 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
24d50 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
24d60 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
24d70 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
24d80 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
24d90 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
24da0 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73  3_uri_int64(cons
24db0 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63  t char*, const c
24dc0 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  har*, sqlite3_in
24dd0 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t64);.../*.** CA
24de0 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
24df0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
24e00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
24e10 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e  te3_errcode() in
24e20 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
24e30 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73  the numeric [res
24e40 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ult code] or.** 
24e50 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
24e60 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d   code] for the m
24e70 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65  ost recent faile
24e80 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  d sqlite3_* API 
24e90 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74  call.** associat
24ea0 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ed with a [datab
24eb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
24ec0 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
24ed0 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62  call failed.** b
24ee0 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ut the most rece
24ef0 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
24f00 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
24f10 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20  n value from.** 
24f20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
24f30 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
24f40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
24f50 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
24f60 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
24f70 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
24f80 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
24f90 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
24fa0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
24fb0 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
24fc0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
24fd0 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
24fe0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
24ff0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
25000 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
25010 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
25020 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
25030 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
25040 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
25050 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
25060 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
25070 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
25080 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
25090 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
250a0 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
250b0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
250c0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
250d0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
250e0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
250f0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
25100 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
25110 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
25120 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
25130 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
25140 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
25150 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
25160 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
25170 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
25180 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
25190 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20  qlite3_errstr() 
251a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
251b0 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61  s the English-la
251c0 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74  nguage text.** t
251d0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
251e0 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c  e [result code],
251f0 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28   as UTF-8..** ^(
25200 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
25210 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
25220 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
25230 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  ed internally.**
25240 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
25250 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70   freed by the ap
25260 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a  plication)^..**.
25270 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
25280 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
25290 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
252a0 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
252b0 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
252c0 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
252d0 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
252e0 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
252f0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
25300 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
25310 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
25320 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
25330 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
25340 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
25350 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
25360 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
25370 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
25380 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
25390 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
253a0 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
253b0 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
253c0 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
253d0 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
253e0 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
253f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25400 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
25410 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
25420 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
25430 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
25440 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
25450 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
25460 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
25470 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
25480 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
25490 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
254a0 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
254b0 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
254c0 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
254d0 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
254e0 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
254f0 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
25500 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
25510 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
25520 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
25530 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
25540 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
25550 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
25560 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
25570 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
25580 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
25590 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  set..*/.SQLITE_A
255a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  PI int sqlite3_e
255b0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
255c0 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  db);.SQLITE_API 
255d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
255e0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
255f0 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54  ite3 *db);.SQLIT
25600 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
25610 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
25620 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
25630 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
25640 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
25650 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53  g16(sqlite3*);.S
25660 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
25670 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
25680 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  rstr(int);../*.*
25690 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
256a0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
256b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
256c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
256d0 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
256e0 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
256f0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
25700 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
25710 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
25720 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  L statement..** 
25730 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76  This object is v
25740 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61  ariously known a
25750 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74  s a "prepared st
25760 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a  atement" or a.**
25770 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73   "compiled SQL s
25780 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d  tatement" or sim
25790 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d  ply as a "statem
257a0 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent"..**.** The 
257b0 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
257c0 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
257d0 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
257e0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
257f0 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
25800 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
25810 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25820 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
25830 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
25840 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
25850 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f  nd values to [ho
25860 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75  st parameters] u
25870 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
25880 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
25890 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
258a0 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
258b0 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
258c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
258d0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
258e0 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
258f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  he statement usi
25900 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
25910 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
25920 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
25930 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
25940 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
25950 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
25960 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
25970 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
25980 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
25990 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f  >.**.** Refer to
259a0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f   documentation o
259b0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74  n individual met
259c0 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61  hods above for a
259d0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
259e0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  ormation..*/.typ
259f0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
25a00 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
25a10 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
25a20 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
25a30 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28   Limits.**.** ^(
25a40 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
25a50 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
25a60 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
25a70 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
25a80 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
25a90 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
25aa0 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
25ab0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
25ac0 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
25ad0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
25ae0 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
25af0 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
25b00 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
25b10 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
25b20 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
25b30 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
25b40 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
25b50 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
25b60 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
25b70 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
25b80 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
25b90 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
25ba0 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
25bb0 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uct.)^.**.** ^If
25bc0 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
25bd0 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
25be0 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
25bf0 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
25c00 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74  ^(For each limit
25c10 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45   category SQLITE
25c20 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f  _LIMIT_<i>NAME</
25c30 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  i> there is a .*
25c40 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
25c50 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
25c60 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
25c70 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70  time by a C prep
25c80 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63  rocessor macro c
25c90 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73  alled.** [limits
25ca0 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69   | SQLITE_MAX_<i
25cb0 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28  >NAME</i>]..** (
25cc0 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e  The "_LIMIT_" in
25cd0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61   the name is cha
25ce0 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e  nged to "_MAX_".
25cf0 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73  ))^.** ^Attempts
25d00 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
25d10 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
25d20 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
25d30 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
25d40 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
25d50 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
25d60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64  d..**.** ^Regard
25d70 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
25d80 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74  or not the limit
25d90 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68   was changed, th
25da0 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  e .** [sqlite3_l
25db0 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63  imit()] interfac
25dc0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72  e returns the pr
25dd0 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65  ior value of the
25de0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63   limit..** ^Henc
25df0 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63  e, to find the c
25e00 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
25e10 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20  a limit without 
25e20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20  changing it,.** 
25e30 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68  simply invoke th
25e40 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74  is interface wit
25e50 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  h the third para
25e60 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e  meter set to -1.
25e70 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20  .**.** Run-time 
25e80 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
25e90 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
25ea0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
25eb0 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
25ec0 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
25ed0 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
25ee0 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
25ef0 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
25f00 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
25f10 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
25f20 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
25f30 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
25f40 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62  ht be a.** web b
25f50 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
25f60 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
25f70 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
25f80 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
25f90 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
25fa0 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61  controlled by Ja
25fb0 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61  vaScript applica
25fc0 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
25fd0 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65  .** off the Inte
25fe0 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
25ff0 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
26000 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
26010 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
26020 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
26030 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
26040 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
26050 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
26060 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
26070 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
26080 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
26090 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
260a0 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65  ttack.  Develope
260b0 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
260c0 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
260d0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
260e0 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
260f0 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
26100 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
26110 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
26120 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
26130 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
26140 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
26150 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
26160 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
26170 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
26180 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
26190 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20  ** New run-time 
261a0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
261b0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
261c0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
261d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
261e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
261f0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
26200 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
26210 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26220 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
26230 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
26240 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
26250 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
26260 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
26270 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
26280 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
26290 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
262a0 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
262b0 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
262c0 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
262d0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
262e0 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
262f0 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
26300 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
26310 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
26320 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
26330 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
26340 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
26350 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
26360 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
26370 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
26380 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
26390 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
263a0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
263b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
263c0 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
263d0 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
263e0 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
263f0 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
26400 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26410 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d  IMIT_SQL_LENGTH]
26420 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26430 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
26440 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26450 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
26460 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
26470 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
26480 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
26490 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
264a0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
264b0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
264c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
264d0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
264e0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
264f0 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
26500 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
26510 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
26520 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
26530 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
26540 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
26550 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
26560 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
26570 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
26580 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26590 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d  IMIT_EXPR_DEPTH]
265a0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
265b0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
265c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
265d0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
265e0 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
265f0 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
26600 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
26610 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
26620 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d  OMPOUND_SELECT]]
26630 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26640 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
26650 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
26660 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
26670 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
26680 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
26690 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
266a0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
266b0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d  E_LIMIT_VDBE_OP]
266c0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
266d0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
266e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
266f0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
26700 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
26710 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
26720 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
26730 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
26740 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
26750 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e   This limit is n
26760 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  ot currently.** 
26770 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68  enforced, though
26780 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61   that might be a
26790 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74  dded in some fut
267a0 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
267b0 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e  * SQLite.</dd>)^
267c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
267d0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
267e0 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  RG]] ^(<dt>SQLIT
267f0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
26800 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
26810 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
26820 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
26830 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
26840 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
26850 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
26860 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  CHED]] ^(<dt>SQL
26870 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
26880 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
26890 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
268a0 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
268b0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
268c0 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
268d0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
268e0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
268f0 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  GTH]].** ^(<dt>S
26900 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
26910 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
26920 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26930 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
26940 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
26950 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
26960 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
26970 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
26980 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
26990 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
269a0 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28  E_NUMBER]].** ^(
269b0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
269c0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
269d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
269e0 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e   maximum index n
269f0 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61  umber of any [pa
26a00 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53  rameter] in an S
26a10 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a  QL statement.)^.
26a20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26a30 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
26a40 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
26a50 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
26a60 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
26a70 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
26a80 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e  pth of recursion
26a90 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f   for triggers.</
26aa0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
26ab0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
26ac0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
26ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26ae0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
26af0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
26b00 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
26b10 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
26b20 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
26b30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26b40 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
26b50 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
26b60 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
26b70 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
26b80 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
26b90 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
26ba0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
26bb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
26bc0 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
26bd0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
26be0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
26bf0 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
26c00 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
26c10 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
26c20 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
26c30 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
26c40 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
26c50 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
26c60 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
26c70 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26c80 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
26c90 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
26ca0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26cb0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
26cc0 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a            10../*
26cd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
26ce0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
26cf0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
26d00 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
26d10 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
26d20 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
26d30 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
26d40 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
26d50 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
26d60 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
26d70 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
26d80 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
26d90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
26da0 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
26db0 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
26dc0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
26dd0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
26de0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
26df0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
26e00 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
26e10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
26e20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
26e30 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
26e40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26e50 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
26e60 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
26e70 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
26e80 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
26e90 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
26ea0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
26eb0 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
26ec0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
26ed0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
26ee0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
26ef0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26f00 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
26f10 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
26f20 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
26f30 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
26f40 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
26f50 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
26f60 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
26f70 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
26f80 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
26f90 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
26fa0 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
26fb0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
26fc0 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
26fd0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
26fe0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
26ff0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
27000 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
27010 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57  d from zSql.  ^W
27020 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
27030 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
27040 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
27050 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
27060 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
27070 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
27080 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42  ter or.** the nB
27090 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
270a0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
270b0 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
270c0 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
270d0 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
270e0 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
270f0 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
27100 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
27110 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
27120 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e  ntage to be gain
27130 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ed by passing an
27140 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
27150 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61   that.** is equa
27160 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  l to the number 
27170 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
27180 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
27190 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
271a0 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
271b0 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69  tor bytes as thi
271c0 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66  s saves SQLite f
271d0 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a  rom having to.**
271e0 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
271f0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
27200 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
27210 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
27220 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
27230 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
27240 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
27250 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
27260 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
27270 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
27280 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
27290 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
272a0 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
272b0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
272c0 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
272d0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
272e0 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
272f0 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
27300 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
27310 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
27320 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
27330 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
27340 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
27350 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
27360 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
27370 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
27380 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
27390 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
273a0 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
273b0 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
273c0 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
273d0 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
273e0 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
273f0 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
27400 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
27410 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
27420 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
27430 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
27440 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
27450 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
27460 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
27470 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
27480 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
27490 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
274a0 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
274b0 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
274c0 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
274d0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
274e0 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
274f0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
27500 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
27510 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
27520 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
27530 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
27540 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
27550 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
27560 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
27570 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
27580 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
27590 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
275a0 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
275b0 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
275c0 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
275d0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
275e0 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
275f0 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
27600 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
27610 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
27620 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
27630 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
27640 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
27650 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
27660 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
27670 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
27680 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
27690 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
276a0 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
276b0 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
276c0 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
276d0 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
276e0 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
276f0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
27700 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
27710 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
27720 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
27730 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
27740 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
27750 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
27760 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
27770 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
27780 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
27790 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
277a0 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
277b0 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41   run it again. A
277c0 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54  s many as [SQLIT
277d0 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54  E_MAX_SCHEMA_RET
277e0 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77  RY].** retries w
277f0 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65  ill occur before
27800 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
27810 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74  gives up and ret
27820 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a  urns an error..*
27830 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
27840 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
27850 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
27860 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
27870 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
27880 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
27890 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
278a0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
278b0 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
278c0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
278d0 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
278e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
278f0 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
27900 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
27910 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
27920 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
27930 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
27940 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
27950 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
27960 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27970 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
27980 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
27990 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
279a0 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
279b0 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
279c0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
279d0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
279e0 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
279f0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
27a00 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
27a10 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
27a20 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
27a30 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
27a40 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
27a50 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
27a60 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
27a70 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
27a80 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
27a90 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
27aa0 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
27ab0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
27ac0 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
27ad0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
27ae0 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
27af0 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
27b00 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
27b10 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
27b20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
27b30 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
27b40 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
27b50 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
27b60 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
27b70 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
27b80 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
27b90 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
27ba0 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
27bb0 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
27bc0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
27bd0 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
27be0 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
27bf0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
27c00 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
27c10 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
27c20 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
27c30 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
27c40 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
27c50 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
27c60 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
27c70 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
27c80 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69  BLE_STAT3] compi
27c90 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
27ca0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f  s enabled..** </
27cb0 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
27cc0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
27cd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
27ce0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
27cf0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
27d00 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
27d10 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
27d20 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
27d30 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
27d40 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
27d50 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
27d60 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
27d70 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
27d80 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
27d90 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
27da0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
27db0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
27dc0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
27dd0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
27de0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
27df0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
27e00 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
27e10 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
27e20 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
27e30 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
27e40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
27e50 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
27e60 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
27e70 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
27e80 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
27e90 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
27ea0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
27eb0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
27ec0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
27ed0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
27ee0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
27ef0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
27f00 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
27f10 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
27f20 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
27f30 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
27f40 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
27f50 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53   of zSql */.);.S
27f60 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
27f70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
27f80 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
27f90 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
27fa0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
27fb0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
27fc0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
27fd0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
27fe0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
27ff0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
28000 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
28010 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
28020 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
28030 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
28040 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
28050 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
28060 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
28070 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
28080 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
28090 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
280a0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
280b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
280c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
280d0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
280e0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
280f0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
28100 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
28110 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
28120 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
28130 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
28140 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
28150 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
28160 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
28170 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
28180 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
28190 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
281a0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
281b0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
281c0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
281d0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
281e0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
281f0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
28200 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
28210 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
28220 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
28230 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
28240 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
28250 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
28260 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
28270 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
28280 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
28290 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
282a0 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
282b0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
282c0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
282d0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
282e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
282f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
28300 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
28310 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
28320 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
28330 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
28340 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
28350 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
28360 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
28370 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
28380 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a  The Database.**.
28390 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
283a0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
283b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
283c0 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
283d0 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
283e0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
283f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
28400 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
28410 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
28420 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
28430 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
28440 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
28450 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
28460 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
28470 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
28480 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
28490 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
284a0 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
284b0 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
284c0 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
284d0 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
284e0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
284f0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
28500 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
28510 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
28520 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
28530 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
28540 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
28550 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
28560 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
28570 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
28580 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
28590 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
285a0 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
285b0 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
285c0 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
285d0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
285e0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
285f0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
28600 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
28610 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
28620 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
28630 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
28640 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
28650 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
28660 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
28670 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
28680 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
28690 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
286a0 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
286b0 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
286c0 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
286d0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
286e0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
286f0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
28700 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
28710 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
28720 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
28730 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
28740 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
28750 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
28760 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
28770 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
28780 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
28790 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
287a0 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
287b0 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
287c0 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
287d0 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
287e0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
287f0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
28800 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
28810 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
28820 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
28830 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
28840 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
28850 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
28860 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
28870 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
28880 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
28890 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  n disk..*/.SQLIT
288a0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
288b0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
288c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
288d0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
288e0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
288f0 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
28900 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
28910 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  n Reset.**.** ^T
28920 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
28930 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63  busy(S) interfac
28940 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
28950 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
28960 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
28970 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62  atement] S has b
28980 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c  een stepped at l
28990 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20  east once using 
289a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
289b0 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f  p(S)] but has no
289c0 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  t run to complet
289d0 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e  ion and/or has n
289e0 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65  ot .** been rese
289f0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
28a00 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68  _reset(S)].  ^Th
28a10 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
28a20 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66  usy(S).** interf
28a30 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73  ace returns fals
28a40 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c  e if S is a NULL
28a50 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20   pointer.  If S 
28a60 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c  is not a .** NUL
28a70 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73  L pointer and is
28a80 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74   not a pointer t
28a90 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61  o a valid [prepa
28aa0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
28ab0 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74  * object, then t
28ac0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
28ad0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
28ae0 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
28af0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
28b00 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
28b10 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69  sed in combinati
28b20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  on [sqlite3_next
28b30 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c  _stmt()].** to l
28b40 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72  ocate all prepar
28b50 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  ed statements as
28b60 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
28b70 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e  database .** con
28b80 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65  nection that are
28b90 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e   in need of bein
28ba0 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63  g reset.  This c
28bb0 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66  an be used,.** f
28bc0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64  or example, in d
28bd0 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e  iagnostic routin
28be0 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72  es to search for
28bf0 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74   prepared .** st
28c00 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  atements that ar
28c10 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e  e holding a tran
28c20 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f  saction open..*/
28c30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
28c40 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
28c50 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
28c60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28c70 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
28c80 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
28c90 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
28ca0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28cb0 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
28cc0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28cd0 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
28ce0 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
28cf0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
28d00 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
28d10 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
28d20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
28d30 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
28d40 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
28d50 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
28d60 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
28d70 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
28d80 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
28d90 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28da0 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
28db0 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
28dc0 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
28dd0 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
28de0 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
28df0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28e00 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
28e10 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
28e20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
28e30 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
28e40 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
28e50 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28e60 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
28e70 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
28e80 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
28e90 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
28ea0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
28eb0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
28ec0 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
28ed0 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
28ee0 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
28ef0 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
28f00 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
28f10 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
28f20 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28f30 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
28f40 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
28f50 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
28f60 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
28f70 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
28f80 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
28f90 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d  .  An internal m
28fa0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
28fb0 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
28fc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28fd0 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
28fe0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
28ff0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
29000 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29010 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
29020 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
29030 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
29040 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
29050 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
29060 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
29070 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
29080 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
29090 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
290a0 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
290b0 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
290c0 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
290d0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
290e0 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
290f0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
29100 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
29110 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
29120 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
29130 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
29140 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
29150 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
29160 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
29170 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
29180 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
29190 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
291a0 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
291b0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
291c0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
291d0 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
291e0 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
291f0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
29200 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
29210 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
29220 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
29230 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
29240 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
29250 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29260 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
29270 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
29280 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
29290 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
292a0 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
292b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
292c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
292d0 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
292e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
292f0 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
29300 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
29310 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
29320 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
29330 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
29340 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
29350 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
29360 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
29370 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
29380 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
29390 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
293a0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
293b0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
293c0 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
293d0 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
293e0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
293f0 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
29400 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
29410 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
29420 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
29430 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
29440 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
29450 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
29460 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
29470 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
29480 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
29490 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
294a0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
294b0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
294c0 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f  t object.  ^A po
294d0 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
294e0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
294f0 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
29500 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
29510 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
29520 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
29530 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
29540 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
29550 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
29560 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
29570 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
29580 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
29590 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
295a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
295b0 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
295c0 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
295d0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
295e0 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
295f0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
29600 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
29610 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
29620 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
29630 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
29640 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
29650 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
29660 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
29670 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
29680 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
29690 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
296a0 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
296b0 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
296c0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57  atements.** KEYW
296d0 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
296e0 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
296f0 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
29700 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
29710 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
29720 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
29730 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
29740 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
29750 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20  .**.** ^(In the 
29760 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
29770 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  xt input to [sql
29780 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
29790 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
297a0 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
297b0 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
297c0 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
297d0 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f  ] that matches o
297e0 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ne of following.
297f0 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a  ** templates:.**
29800 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
29810 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
29820 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
29830 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
29840 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
29850 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
29860 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76  e templates abov
29870 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74  e, NNN represent
29880 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
29890 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
298a0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61   represents an a
298b0 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e  lphanumeric iden
298c0 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20  tifier.)^  ^The 
298d0 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
298e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
298f0 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
29900 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
29910 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
29920 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
29930 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
29940 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
29950 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
29960 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
29970 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
29980 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
29990 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
299a0 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
299b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
299c0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
299d0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
299e0 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
299f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
29a00 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
29a10 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
29a20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
29a30 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
29a40 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
29a50 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
29a60 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
29a70 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
29a80 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
29a90 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
29aa0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
29ab0 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
29ac0 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
29ad0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
29ae0 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
29af0 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
29b00 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
29b10 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
29b20 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
29b30 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
29b40 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
29b50 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
29b60 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29b70 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
29b80 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
29b90 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
29ba0 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
29bb0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
29bc0 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
29bd0 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
29be0 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
29bf0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
29c00 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
29c10 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
29c20 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
29c30 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
29c40 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
29c50 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
29c60 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
29c70 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
29c80 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  meter..** ^If th
29c90 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
29ca0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
29cb0 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
29cc0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
29cd0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
29ce0 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61  bind_blob() is a
29cf0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
29d00 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  en the fourth pa
29d10 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67  rameter.** is ig
29d20 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e  nored and the en
29d30 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20  d result is the 
29d40 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f  same as sqlite3_
29d50 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a  bind_null()..**.
29d60 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
29d70 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
29d80 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
29d90 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
29da0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
29db0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
29dc0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
29dd0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
29de0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
29df0 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
29e00 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
29e10 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
29e20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
29e30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
29e40 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
29e50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29e60 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
29e70 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
29e80 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
29e90 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  n the length of 
29ea0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
29eb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
29ec0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
29ed0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
29ee0 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ator..** If the 
29ef0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
29f00 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
29f10 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74  _blob() is negat
29f20 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ive, then.** the
29f30 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
29f40 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20  efined..** If a 
29f50 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75  non-negative fou
29f60 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
29f70 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c   provided to sql
29f80 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
29f90 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
29fa0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65  ind_text16() the
29fb0 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  n that parameter
29fc0 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
29fd0 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72  e offset.** wher
29fe0 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
29ff0 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72  ator would occur
2a000 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74   assuming the st
2a010 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a  ring were NUL.**
2a020 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
2a030 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
2a040 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74  ers occur at byt
2a050 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74  e offsets less t
2a060 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75  han .** the valu
2a070 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  e of the fourth 
2a080 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74  parameter then t
2a090 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
2a0a0 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a  ing value will.*
2a0b0 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  * contain embedd
2a0c0 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65  ed NULs.  The re
2a0d0 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
2a0e0 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74  ons involving st
2a0f0 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d  rings.** with em
2a100 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
2a110 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2a120 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
2a130 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
2a140 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  ind_blob(), sqli
2a150 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
2a160 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
2a170 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73  bind_text16() is
2a180 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
2a190 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
2a1a0 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
2a1b0 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
2a1c0 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
2a1d0 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
2a1e0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
2a1f0 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
2a200 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2a210 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
2a220 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c   the call to sql
2a230 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2a240 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  ,.** sqlite3_bin
2a250 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c  d_text(), or sql
2a260 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2a270 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e  () fails.  .** ^
2a280 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
2a290 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
2a2a0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
2a2b0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
2a2c0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
2a2d0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
2a2e0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
2a2f0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
2a300 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
2a310 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2a320 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
2a330 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2a340 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
2a350 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
2a360 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
2a370 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
2a380 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
2a390 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
2a3a0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
2a3b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2a3c0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
2a3d0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
2a3e0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
2a3f0 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
2a400 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
2a410 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
2a420 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
2a430 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65  h zeroes.  ^A ze
2a440 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
2a450 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
2a460 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
2a470 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
2a480 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
2a490 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
2a4a0 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
2a4b0 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
2a4c0 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
2a4d0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
2a4e0 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
2a4f0 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
2a500 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
2a510 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
2a520 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
2a530 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
2a540 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  nes..** ^A negat
2a550 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
2a560 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
2a570 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
2a580 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
2a590 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73  ^If any of the s
2a5a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2a5b0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2a5c0 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
2a5d0 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74  pointer.** for t
2a5e0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2a5f0 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20  tement] or with 
2a600 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2a610 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a  ment for which.*
2a620 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2a630 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
2a640 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79  ed more recently
2a650 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72   than [sqlite3_r
2a660 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  eset()],.** then
2a670 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72   the call will r
2a680 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  eturn [SQLITE_MI
2a690 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73  SUSE].  If any s
2a6a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a  qlite3_bind_().*
2a6b0 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73  * routine is pas
2a6c0 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20  sed a [prepared 
2a6d0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2a6e0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2a6f0 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  ed, the.** resul
2a700 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  t is undefined a
2a710 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d  nd probably harm
2a720 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64  ful..**.** ^Bind
2a730 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
2a740 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
2a750 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
2a760 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75  utine..** ^Unbou
2a770 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
2a780 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
2a790 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
2a7a0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2a7b0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2a7c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
2a7d0 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a  success or an.**
2a7e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
2a7f0 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
2a800 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  rong..** ^[SQLIT
2a810 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
2a820 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
2a830 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
2a840 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
2a850 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
2a860 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2a870 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
2a880 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2a890 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2a8a0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2a8b0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2a8c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2a8d0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
2a8e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2a8f0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53  r_index()]..*/.S
2a900 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2a910 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2a920 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a930 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2a940 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
2a950 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
2a960 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2a970 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
2a980 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2a990 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f  double);.SQLITE_
2a9a0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2a9b0 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
2a9c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
2a9d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2a9e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
2a9f0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2aa00 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
2aa10 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f  _int64);.SQLITE_
2aa20 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2aa30 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
2aa40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53  3_stmt*, int);.S
2aa50 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2aa60 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2aa70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2aa80 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
2aa90 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
2aaa0 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
2aab0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2aac0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
2aad0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2aae0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2aaf0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2ab00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2ab10 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
2ab20 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
2ab30 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
2ab40 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2ab50 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2ab60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2ab70 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2ab80 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
2ab90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2aba0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
2abb0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
2abc0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
2abd0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
2abe0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
2abf0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
2ac00 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
2ac10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2ac20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
2ac30 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
2ac40 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
2ac50 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
2ac60 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
2ac70 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
2ac80 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
2ac90 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
2aca0 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
2acb0 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
2acc0 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
2acd0 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
2ace0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
2acf0 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
2ad00 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
2ad10 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
2ad20 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
2ad30 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
2ad40 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
2ad50 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
2ad60 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
2ad70 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2ad80 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
2ad90 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
2ada0 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
2adb0 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
2adc0 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
2add0 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
2ade0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
2adf0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2ae00 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2ae10 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2ae20 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2ae30 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
2ae40 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2ae50 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2ae60 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2ae70 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2ae80 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2ae90 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2aea0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2aeb0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
2aec0 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a  st Parameter.**.
2aed0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2aee0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2aef0 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
2af00 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
2af10 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
2af20 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
2af30 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
2af40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2af50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
2af60 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2af70 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
2af80 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2af90 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
2afa0 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
2afb0 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
2afc0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2afd0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2afe0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
2aff0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2b000 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
2b010 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
2b020 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
2b030 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
2b040 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
2b050 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
2b060 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
2b070 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
2b080 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
2b090 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
2b0a0 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
2b0b0 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
2b0c0 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
2b0d0 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
2b0e0 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
2b0f0 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
2b100 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
2b110 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
2b120 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
2b130 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
2b140 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
2b150 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
2b160 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
2b170 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
2b180 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
2b190 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
2b1a0 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
2b1b0 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
2b1c0 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
2b1d0 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
2b1e0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
2b1f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b200 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
2b210 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2b220 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
2b230 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2b240 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2b250 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2b260 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2b270 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
2b280 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2b290 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2b2a0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
2b2b0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2b2c0 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
2b2d0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
2b2e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b2f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b300 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
2b310 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
2b320 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a  Given Name.**.**
2b330 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
2b340 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
2b350 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
2b360 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
2b370 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
2b380 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
2b390 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
2b3a0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
2b3b0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
2b3c0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2b3d0 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
2b3e0 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
2b3f0 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
2b400 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
2b410 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
2b420 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
2b430 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
2b440 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
2b450 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
2b460 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
2b470 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
2b480 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
2b490 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2b4a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
2b4b0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2b4c0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2b4d0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2b4e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2b4f0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
2b500 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2b510 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2b520 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
2b530 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2b540 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2b550 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
2b560 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
2b570 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
2b580 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2b590 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
2b5a0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2b5b0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74  ment.**.** ^Cont
2b5c0 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
2b5d0 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
2b5e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2b5f0 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
2b600 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2b610 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
2b620 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
2b630 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2b640 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f  .** ^Use this ro
2b650 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
2b660 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
2b670 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53  rs to NULL..*/.S
2b680 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2b690 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2b6a0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2b6b0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2b6c0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
2b6d0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
2b6e0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
2b6f0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
2b700 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2b710 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
2b720 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2b730 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b740 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
2b750 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2b760 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
2b770 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
2b780 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
2b790 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
2b7a0 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
2b7b0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
2b7c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
2b7d0 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51  a_count()].*/.SQ
2b7e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2b7f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2b800 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2b810 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2b820 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
2b830 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
2b840 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t Set.**.** ^The
2b850 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2b860 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
2b870 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
2b880 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
2b890 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2b8a0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
2b8b0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
2b8c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2b8d0 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
2b8e0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2b8f0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
2b900 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
2b910 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
2b920 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2b930 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
2b940 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2b950 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
2b960 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2b970 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
2b980 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
2b990 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b9a0 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
2b9b0 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
2b9c0 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
2b9d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2b9e0 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
2b9f0 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
2ba00 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
2ba10 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
2ba20 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2ba30 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
2ba40 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2ba50 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
2ba60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2ba70 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
2ba80 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
2ba90 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2baa0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2bab0 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2bac0 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2bad0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2bae0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2baf0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2bb00 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2bb10 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
2bb20 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
2bb30 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
2bb40 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2bb50 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
2bb60 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
2bb70 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
2bb80 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
2bb90 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
2bba0 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
2bbb0 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
2bbc0 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
2bbd0 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
2bbe0 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
2bbf0 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
2bc00 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2bc10 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2bc20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
2bc30 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
2bc40 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
2bc50 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
2bc60 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
2bc70 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
2bc80 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
2bc90 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
2bca0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
2bcb0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
2bcc0 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
2bcd0 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
2bce0 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
2bcf0 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
2bd00 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54  e next..*/.SQLIT
2bd10 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2bd20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2bd30 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2bd40 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c  mt*, int N);.SQL
2bd50 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2bd60 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2bd70 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
2bd80 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
2bd90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bda0 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
2bdb0 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
2bdc0 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  lt.**.** ^These 
2bdd0 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
2bde0 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
2bdf0 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61  rmine the databa
2be00 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a  se, table, and.*
2be10 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  * table column t
2be20 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69  hat is the origi
2be30 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61  n of a particula
2be40 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  r result column 
2be50 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73  in.** [SELECT] s
2be60 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  tatement..** ^Th
2be70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
2be80 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
2be90 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
2bea0 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
2beb0 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
2bec0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
2bed0 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65    ^The _database
2bee0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2bef0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
2bf00 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
2bf10 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
2bf20 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
2bf30 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
2bf40 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
2bf50 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
2bf60 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  n name..** ^The 
2bf70 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2bf80 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
2bf90 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2bfa0 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
2bfb0 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
2bfc0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2bfd0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2bfe0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2bff0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2c000 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2c010 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2c020 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2c030 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2c040 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2c050 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
2c060 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
2c070 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
2c080 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
2c090 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
2c0a0 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
2c0b0 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
2c0c0 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
2c0d0 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
2c0e0 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
2c0f0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
2c100 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2c110 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
2c120 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
2c130 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2c140 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
2c150 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
2c160 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
2c170 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
2c180 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
2c190 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
2c1a0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
2c1b0 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
2c1c0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
2c1d0 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
2c1e0 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
2c1f0 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
2c200 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
2c210 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
2c220 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
2c230 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
2c240 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
2c250 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
2c260 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
2c270 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
2c280 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
2c290 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
2c2a0 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
2c2b0 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
2c2c0 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
2c2d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
2c2e0 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
2c2f0 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
2c300 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
2c310 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
2c320 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
2c330 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
2c340 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
2c350 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
2c360 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
2c370 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
2c380 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
2c390 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
2c3a0 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
2c3b0 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
2c3c0 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
2c3d0 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
2c3e0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
2c3f0 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
2c400 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
2c410 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
2c420 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
2c430 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
2c440 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
2c450 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
2c460 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
2c470 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
2c480 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
2c490 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
2c4a0 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
2c4b0 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
2c4c0 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
2c4d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c4e0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
2c4f0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
2c500 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2c510 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
2c520 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2c530 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2c540 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
2c550 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c560 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
2c570 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
2c580 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
2c590 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
2c5a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c5b0 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
2c5c0 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
2c5d0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
2c5e0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2c5f0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  efined..*/.SQLIT
2c600 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2c610 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2c620 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
2c630 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2c640 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2c650 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2c660 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2c670 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2c680 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2c690 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2c6a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2c6b0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
2c6c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2c6d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2c6e0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2c6f0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
2c700 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2c710 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2c720 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2c730 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
2c740 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
2c750 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2c760 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2c770 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2c780 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2c790 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2c7a0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2c7b0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
2c7c0 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
2c7d0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
2c7e0 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
2c7f0 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
2c800 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c810 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
2c820 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
2c830 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
2c840 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
2c850 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
2c860 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
2c870 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
2c880 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
2c890 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
2c8a0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2c8b0 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
2c8c0 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
2c8d0 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
2c8e0 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
2c8f0 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
2c900 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2c910 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
2c920 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2c930 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
2c940 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2c950 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
2c960 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2c970 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
2c980 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
2c990 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2c9a0 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
2c9b0 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
2c9c0 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
2c9d0 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
2c9e0 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
2c9f0 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
2ca00 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
2ca10 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
2ca20 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
2ca30 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
2ca40 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
2ca50 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
2ca60 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
2ca70 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
2ca80 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
2ca90 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
2caa0 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
2cab0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
2cac0 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
2cad0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2cae0 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
2caf0 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
2cb00 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
2cb10 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
2cb20 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
2cb30 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
2cb40 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
2cb50 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
2cb60 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
2cb70 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
2cb80 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
2cb90 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
2cba0 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
2cbb0 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
2cbc0 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
2cbd0 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
2cbe0 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
2cbf0 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
2cc00 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
2cc10 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
2cc20 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
2cc30 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  es..*/.SQLITE_AP
2cc40 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2cc50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
2cc60 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
2cc70 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2cc80 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2cc90 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2cca0 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
2ccb0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
2ccc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ccd0 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
2cce0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
2ccf0 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
2cd00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
2cd10 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
2cd20 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
2cd30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2cd40 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
2cd50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2cd60 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
2cd70 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2cd80 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
2cd90 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
2cda0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2cdb0 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
2cdc0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
2cdd0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
2cde0 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
2cdf0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
2ce00 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
2ce10 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
2ce20 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
2ce30 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
2ce40 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
2ce50 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
2ce60 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
2ce70 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
2ce80 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
2ce90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2cea0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
2ceb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2cec0 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
2ced0 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
2cee0 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
2cef0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
2cf00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2cf10 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
2cf20 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
2cf30 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
2cf40 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
2cf50 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
2cf60 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
2cf70 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
2cf80 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
2cf90 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
2cfa0 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
2cfb0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
2cfc0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
2cfd0 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
2cfe0 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
2cff0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
2d000 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
2d010 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
2d020 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
2d030 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
2d040 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
2d050 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
2d060 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
2d070 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
2d080 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
2d090 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
2d0a0 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
2d0b0 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
2d0c0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
2d0d0 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
2d0e0 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
2d0f0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
2d100 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
2d110 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
2d120 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2d130 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
2d140 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
2d150 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
2d160 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
2d170 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
2d180 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
2d190 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
2d1a0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
2d1b0 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
2d1c0 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a  urs within an.**
2d1d0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2d1e0 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
2d1f0 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
2d200 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
2d210 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
2d220 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ing..**.** ^[SQL
2d230 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
2d240 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
2d250 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
2d260 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
2d270 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
2d280 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2d290 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2d2a0 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
2d2b0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
2d2c0 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
2d2d0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2d2e0 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
2d2f0 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
2d300 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
2d310 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
2d320 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te..**.** ^If th
2d330 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2d340 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
2d350 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
2d360 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   then [SQLITE_RO
2d370 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  W].** is returne
2d380 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
2d390 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
2d3a0 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65   ready for proce
2d3b0 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20  ssing by the.** 
2d3c0 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
2d3d0 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
2d3e0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f  ed using the [co
2d3f0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2d400 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
2d410 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
2d420 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
2d430 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
2d440 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ow of data..**.*
2d450 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  * ^[SQLITE_ERROR
2d460 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
2d470 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
2d480 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
2d490 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
2d4a0 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
2d4b0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2d4c0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2d4d0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
2d4e0 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
2d4f0 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
2d500 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
2d510 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
2d520 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  g()]..** ^With t
2d530 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2d540 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
2d550 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2d560 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
2d570 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
2d580 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
2d590 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
2d5a0 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
2d5b0 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
2d5c0 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
2d5d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2d5e0 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
2d5f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d600 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22  ent].  ^In the "
2d610 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
2d620 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
2d630 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
2d640 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
2d650 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
2d660 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
2d670 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
2d680 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
2d690 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
2d6a0 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
2d6b0 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
2d6c0 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
2d6d0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2d6e0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
2d6f0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
2d700 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2d710 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
2d720 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
2d730 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
2d740 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2d750 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
2d760 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
2d770 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
2d780 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
2d790 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
2d7a0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
2d7b0 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
2d7c0 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
2d7d0 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
2d7e0 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
2d7f0 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69  ** For all versi
2d800 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70  ons of SQLite up
2d810 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e   to and includin
2d820 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61  g 3.6.23.1, a ca
2d830 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2d840 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72  3_reset()] was r
2d850 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71  equired after sq
2d860 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74  lite3_step() ret
2d870 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a  urned anything.*
2d880 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  * other than [SQ
2d890 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65  LITE_ROW] before
2d8a0 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
2d8b0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
2d8c0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2d8d0 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73    Failure to res
2d8e0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
2d8f0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
2d900 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2d910 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75  et()] would resu
2d920 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  lt in an [SQLITE
2d930 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20  _MISUSE] return 
2d940 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
2d950 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74  step().  But aft
2d960 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32  er version 3.6.2
2d970 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  3.1, sqlite3_ste
2d980 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c  p() began.** cal
2d990 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2d9a0 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63  set()] automatic
2d9b0 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
2d9c0 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
2d9d0 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69  .** than returni
2d9e0 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
2d9f0 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  E].  This is not
2da00 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f   considered a co
2da10 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62  mpatibility.** b
2da20 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79  reak because any
2da30 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
2da40 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20  t ever receives 
2da50 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  an SQLITE_MISUSE
2da60 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f   error.** is bro
2da70 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f  ken by definitio
2da80 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  n.  The [SQLITE_
2da90 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20  OMIT_AUTORESET] 
2daa0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2dab0 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ion.** can be us
2dac0 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68  ed to restore th
2dad0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
2dae0 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  r..**.** <b>Goof
2daf0 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
2db00 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
2db10 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2db20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2db30 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
2db40 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
2db50 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
2db60 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
2db70 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
2db80 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
2db90 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
2dba0 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
2dbb0 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
2dbc0 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
2dbd0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
2dbe0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2dbf0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
2dc00 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
2dc10 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
2dc20 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
2dc30 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
2dc40 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
2dc50 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
2dc60 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
2dc70 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
2dc80 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
2dc90 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2dca0 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
2dcb0 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
2dcc0 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
2dcd0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
2dce0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
2dcf0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2dd00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2dd10 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
2dd20 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
2dd30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2dd40 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2dd50 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
2dd60 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
2dd70 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
2dd80 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2dd90 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
2dda0 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
2ddb0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
2ddc0 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32  e use of the "v2
2ddd0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2dde0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53  ecommended..*/.S
2ddf0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2de00 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
2de10 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2de20 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2de30 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2de40 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
2de50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2de60 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
2de70 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2de80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2de90 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
2dea0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
2deb0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2dec0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
2ded0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
2dee0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2def0 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
2df00 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
2df10 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
2df20 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
2df30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2df40 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
2df50 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
2df60 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
2df70 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
2df80 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
2df90 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
2dfa0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2dfb0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
2dfc0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
2dfd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2dfe0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2dff0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
2e000 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2e010 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
2e020 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2e030 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2e040 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
2e050 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
2e060 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2e070 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
2e080 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
2e090 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
2e0a0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2e0b0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
2e0c0 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
2e0d0 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
2e0e0 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
2e0f0 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
2e100 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
2e110 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
2e120 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
2e130 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
2e140 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
2e150 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
2e160 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
2e170 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2e180 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
2e190 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2e1a0 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
2e1b0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2e1c0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2e1d0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
2e1e0 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
2e1f0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
2e200 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
2e210 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69   ^(Every value i
2e220 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
2e230 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
2e240 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
2e250 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2e260 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
2e270 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
2e280 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
2e290 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
2e2a0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
2e2b0 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
2e2c0 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
2e2d0 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
2e2e0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
2e2f0 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
2e300 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
2e310 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2e320 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
2e330 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
2e340 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
2e350 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
2e360 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
2e370 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
2e380 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
2e390 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
2e3a0 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
2e3b0 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
2e3c0 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
2e3d0 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
2e3e0 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
2e3f0 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
2e400 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
2e410 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
2e420 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
2e430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e440 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
2e450 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
2e460 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
2e470 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
2e480 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
2e490 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
2e4a0 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
2e4b0 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
2e4c0 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
2e4d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e4e0 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
2e4f0 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45  om A Query.** KE
2e500 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20  YWORDS: {column 
2e510 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2e520 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
2e530 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20  utines form the 
2e540 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74  "result set" int
2e550 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  erface..**.** ^T
2e560 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
2e570 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
2e580 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20   about a single 
2e590 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75  column of the cu
2e5a0 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20  rrent.** result 
2e5b0 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
2e5c0 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20   ^In every case 
2e5d0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2e5e0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a  nt is a pointer.
2e5f0 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  ** to the [prepa
2e600 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2e610 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61  hat is being eva
2e620 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
2e630 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74  ite3_stmt*].** t
2e640 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
2e650 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
2e660 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2e670 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
2e680 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  nts).** and the 
2e690 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2e6a0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
2e6b0 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
2e6c0 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
2e6d0 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
2e6e0 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66  turned. ^The lef
2e6f0 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  tmost column of 
2e700 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68  the result set h
2e710 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a  as the index 0..
2e720 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  ** ^The number o
2e730 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2e740 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64   result can be d
2e750 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a  etermined using.
2e760 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2e770 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a  mn_count()]..**.
2e780 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
2e790 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2e7a0 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
2e7b0 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
2e7c0 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f   or if the.** co
2e7d0 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
2e7e0 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
2e7f0 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
2e800 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ned..** These ro
2e810 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
2e820 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
2e830 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2e840 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2e850 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2e860 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2e870 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
2e880 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2e890 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
2e8a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
2e8b0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
2e8c0 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
2e8d0 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
2e8e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2e8f0 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
2e900 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2e910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2e920 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
2e930 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2e940 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
2e950 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
2e960 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
2e970 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
2e980 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2e990 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
2e9a0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
2e9b0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
2e9c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e9d0 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
2e9e0 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
2e9f0 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
2ea00 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2ea10 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
2ea20 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
2ea30 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2ea40 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2ea50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ea60 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
2ea70 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
2ea80 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
2ea90 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
2eaa0 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
2eab0 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
2eac0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
2ead0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
2eae0 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
2eaf0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2eb00 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
2eb10 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
2eb20 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
2eb30 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
2eb40 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
2eb50 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
2eb60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2eb70 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
2eb80 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
2eb90 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
2eba0 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
2ebb0 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
2ebc0 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
2ebd0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
2ebe0 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
2ebf0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2ec00 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
2ec10 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
2ec20 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
2ec30 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
2ec40 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
2ec50 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
2ec60 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
2ec70 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
2ec80 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
2ec90 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2eca0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2ecb0 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
2ecc0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2ecd0 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
2ece0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2ecf0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2ed00 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2ed10 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2ed20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2ed30 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
2ed40 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2ed50 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
2ed60 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
2ed70 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
2ed80 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2ed90 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2eda0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2edb0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2edc0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2edd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ede0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
2edf0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
2ee00 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
2ee10 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
2ee20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2ee30 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
2ee40 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2ee50 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
2ee60 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
2ee70 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
2ee80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2ee90 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
2eea0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
2eeb0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
2eec0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74   UTF-16 string t
2eed0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
2eee0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2eef0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
2ef00 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2ef10 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2ef20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
2ef30 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2ef40 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  t is a UTF-8 str
2ef50 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
2ef60 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2ef70 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2ef80 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2ef90 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74  -16 and then ret
2efa0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2efb0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
2efc0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2efd0 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2efe0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2eff0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65  mn_bytes16() use
2f000 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2f010 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2f020 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2f030 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  to a UTF-16 stri
2f040 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2f050 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2f060 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
2f070 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2f080 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
2f090 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2f0a0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
2f0b0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
2f0c0 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  ** ^The values r
2f0d0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
2f0e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f0f0 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  ()] and .** [sql
2f100 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f110 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e  s16()] do not in
2f120 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
2f130 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68  erminators at th
2f140 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
2f150 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
2f160 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
2f170 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
2f180 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2f190 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73  _bytes()] and [s
2f1a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f1b0 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65  tes16()] are the
2f1c0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
2f1d0 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
2f1e0 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
2f1f0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2f200 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
2f210 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2f220 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2f230 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
2f240 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
2f250 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
2f260 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
2f270 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2f280 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
2f290 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
2f2a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2f2b0 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
2f2c0 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e  ngth BLOB is a N
2f2d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
2f2e0 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72  ** ^The object r
2f2f0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
2f300 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2f310 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
2f320 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2f330 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
2f340 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64    An unprotected
2f350 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2f360 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  bject.** may onl
2f370 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b  y be used with [
2f380 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2f390 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
2f3a0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2f3b0 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
2f3c0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2f3d0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2f3e0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2f3f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2f400 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
2f410 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
2f420 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
2f430 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
2f440 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
2f450 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
2f460 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2f470 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
2f480 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2f490 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ()], then the be
2f4a0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2f4b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ned..**.** These
2f4c0 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
2f4d0 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
2f4e0 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
2f4f0 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a  ropriate.  ^For.
2f500 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
2f510 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
2f520 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
2f530 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
2f540 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
2f550 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
2f560 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
2f570 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
2f580 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
2f590 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
2f5a0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68  matically.  ^(Th
2f5b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
2f5c0 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
2f5d0 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
2f5e0 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
2f5f0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2f600 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
2f610 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
2f620 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
2f630 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
2f640 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
2f650 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
2f660 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2f670 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
2f680 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
2f690 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
2f6a0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2f6b0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
2f6c0 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
2f6d0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2f6e0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2f6f0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
2f700 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2f710 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2f720 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2f730 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2f740 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2f750 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2f760 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
2f770 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
2f780 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
2f790 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2f7a0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2f7b0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2f7c0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
2f7d0 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
2f7e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2f7f0 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
2f800 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
2f810 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
2f820 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2f830 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2f840 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2f850 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
2f860 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2f870 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2f880 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2f890 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
2f8a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2f8b0 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
2f8c0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2f8d0 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74  o BLOB.** <tr><t
2f8e0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2f8f0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2f900 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
2f910 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  R.** <tr><td>  T
2f920 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
2f930 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
2f940 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
2f950 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2f960 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2f970 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
2f980 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2f990 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2f9a0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2f9b0 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
2f9c0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2f9d0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2f9e0 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
2f9f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2fa00 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
2fa10 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
2fa20 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
2fa30 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
2fa40 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
2fa50 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  uote>)^.**.** Th
2fa60 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61  e table above ma
2fa70 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f  kes reference to
2fa80 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
2fa90 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74  ary functions at
2faa0 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66  oi().** and atof
2fab0 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73  ().  SQLite does
2fac0 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20   not really use 
2fad0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
2fae0 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20    It has its.** 
2faf0 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69  own equivalent i
2fb00 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
2fb10 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
2fb20 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
2fb30 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
2fb40 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
2fb50 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
2fb60 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
2fb70 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
2fb80 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
2fb90 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
2fba0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2fbb0 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
2fbc0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
2fbd0 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
2fbe0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fbf0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
2fc00 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
2fc10 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
2fc20 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2fc30 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
2fc40 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
2fc50 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
2fc60 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
2fc70 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
2fc80 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
2fc90 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
2fca0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
2fcb0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2fcc0 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
2fcd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2fce0 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
2fcf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2fd00 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
2fd10 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
2fd20 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
2fd30 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
2fd40 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
2fd50 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
2fd60 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2fd70 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
2fd80 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
2fd90 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
2fda0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2fdb0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2fdc0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2fdd0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2fde0 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2fdf0 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
2fe00 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2fe10 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2fe20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
2fe30 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2fe40 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2fe50 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2fe60 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
2fe70 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
2fe80 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
2fe90 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
2fea0 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
2feb0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
2fec0 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
2fed0 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
2fee0 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
2fef0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
2ff00 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
2ff10 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
2ff20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
2ff30 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
2ff40 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
2ff50 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
2ff60 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
2ff70 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
2ff80 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
2ff90 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
2ffa0 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
2ffb0 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
2ffc0 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
2ffd0 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
2ffe0 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
2fff0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
30000 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
30010 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
30020 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
30030 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
30040 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
30050 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
30060 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
30070 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
30080 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
30090 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
300a0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
300b0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
300c0 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
300d0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
300e0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
300f0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
30100 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
30110 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
30120 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
30130 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
30140 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30150 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
30160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30170 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
30180 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
30190 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
301a0 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
301b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
301c0 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
301d0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
301e0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
301f0 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
30200 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
30210 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
30220 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
30230 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
30240 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30250 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
30260 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
30270 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
30280 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
30290 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
302a0 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
302b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
302c0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
302d0 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
302e0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
302f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
30300 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
30310 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
30320 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
30330 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
30340 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
30350 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
30360 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
30370 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
30380 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
30390 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
303a0 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
303b0 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
303c0 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
303d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
303e0 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
303f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30400 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
30410 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
30420 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
30430 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
30440 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
30450 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
30460 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
30470 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
30480 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
30490 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
304a0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
304b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
304c0 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
304d0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
304e0 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f  *.** ^(If a memo
304f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
30500 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
30510 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
30520 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
30530 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
30540 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
30550 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
30560 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
30570 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
30580 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
30590 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
305a0 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
305b0 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
305c0 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
305d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
305e0 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
305f0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
30600 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49  OMEM].)^.*/.SQLI
30610 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
30620 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
30630 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
30640 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30650 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
30660 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30670 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
30680 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
30690 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
306a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
306b0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
306c0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
306d0 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65  QLITE_API double
306e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
306f0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
30700 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30710 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
30720 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
30730 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
30740 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
30750 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
30760 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
30770 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
30780 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
30790 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
307a0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
307b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
307c0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
307d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
307e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
307f0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
30800 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
30810 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30820 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
30830 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
30840 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
30850 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
30860 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
30870 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  I sqlite3_value 
30880 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30890 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
308a0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
308b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
308c0 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
308d0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
308e0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ject.**.** ^The 
308f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30900 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
30910 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
30920 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
30930 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
30940 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
30950 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
30960 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
30970 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
30980 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
30990 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
309a0 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
309b0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
309c0 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
309d0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
309e0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
309f0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
30a00 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
30a10 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
30a20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
30a30 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
30a40 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
30a50 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
30a60 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
30a70 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
30a80 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
30a90 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
30aa0 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
30ab0 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
30ac0 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
30ad0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
30ae0 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
30af0 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
30b00 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
30b10 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
30b20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
30b30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30b40 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
30b50 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
30b60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
30b70 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
30b80 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
30b90 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
30ba0 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
30bb0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
30bc0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
30bd0 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
30be0 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
30bf0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
30c00 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
30c10 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
30c20 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
30c30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
30c40 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
30c50 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
30c60 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
30c70 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
30c80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
30c90 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
30ca0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
30cb0 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
30cc0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
30cd0 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
30ce0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
30cf0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
30d00 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
30d10 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
30d20 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
30d30 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
30d40 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
30d50 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
30d60 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53  corruption..*/.S
30d70 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
30d80 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
30d90 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
30da0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
30db0 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
30dc0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
30dd0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
30de0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
30df0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
30e00 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
30e10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30e20 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
30e30 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
30e40 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
30e50 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
30e60 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
30e70 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
30e80 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
30e90 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
30ea0 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
30eb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
30ec0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
30ed0 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
30ee0 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
30ef0 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
30f00 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
30f10 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
30f20 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
30f30 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
30f40 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
30f50 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
30f60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
30f70 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
30f80 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
30f90 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
30fa0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
30fb0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
30fc0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
30fd0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
30fe0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
30ff0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
31000 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
31010 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
31020 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
31030 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
31040 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
31050 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
31060 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
31070 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
31080 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
31090 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
310a0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
310b0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
310c0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
310d0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
310e0 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
310f0 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
31100 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
31110 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
31120 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
31130 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
31140 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
31150 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
31160 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
31170 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
31180 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
31190 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
311a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
311b0 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49  ment] S..*/.SQLI
311c0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
311d0 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
311e0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
311f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31200 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
31210 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
31220 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
31230 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
31240 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
31250 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
31260 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
31270 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
31280 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
31290 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
312a0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
312b0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
312c0 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
312d0 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
312e0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
312f0 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
31300 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
31310 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
31320 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
31330 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
31340 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
31350 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
31360 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
31370 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
31380 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20  nces between.** 
31390 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
313a0 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  re the text enco
313b0 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f  ding expected fo
313c0 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  r.** the second 
313d0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e  parameter (the n
313e0 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ame of the funct
313f0 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65  ion being create
31400 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72  d).** and the pr
31410 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63  esence or absenc
31420 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f  e of a destructo
31430 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a  r callback for.*
31440 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
31450 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a  n data pointer..
31460 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
31470 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
31480 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
31490 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
314a0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
314b0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
314c0 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70  ded.  ^If an app
314d0 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f  lication uses mo
314e0 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
314f0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
31500 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74  on then applicat
31510 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
31520 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
31530 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61  e added.** to ea
31540 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
31550 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c  ection separatel
31560 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  y..**.** ^The se
31570 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
31580 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
31590 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
315a0 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
315b0 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e  ** redefined.  ^
315c0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
315d0 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
315e0 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69  d to 255 bytes i
315f0 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70  n a UTF-8.** rep
31600 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63  resentation, exc
31610 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65  lusive of the ze
31620 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
31630 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e  ^Note that the n
31640 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69  ame.** length li
31650 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20  mit is in UTF-8 
31660 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61  bytes, not chara
31670 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36  cters nor UTF-16
31680 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e   bytes.  .** ^An
31690 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
316a0 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
316b0 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
316c0 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
316d0 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   in [SQLITE_MISU
316e0 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  SE] being return
316f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  ed..**.** ^The t
31700 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
31710 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
31720 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
31730 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
31740 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
31750 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
31760 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65   ^If this parame
31770 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ter is -1, then 
31780 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
31790 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
317a0 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
317b0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
317c0 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  s between 0 and 
317d0 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74  the limit.** set
317e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
317f0 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
31800 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29  T_FUNCTION_ARG])
31810 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a  .  If the third.
31820 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
31830 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20  less than -1 or 
31840 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
31850 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
31860 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e  or is.** undefin
31870 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
31880 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
31890 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
318a0 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
318b0 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
318c0 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
318d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
318e0 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
318f0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65  parameters.  The
31900 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
31910 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72  uld set this par
31920 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51  ameter to.** [SQ
31930 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66  LITE_UTF16LE] if
31940 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d   the function im
31950 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
31960 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  okes .** [sqlite
31970 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
31980 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
31990 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
319a0 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69  6BE] if the.** i
319b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
319c0 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76  vokes [sqlite3_v
319d0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d  alue_text16be()]
319e0 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
319f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
31a00 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76  6] if [sqlite3_v
31a10 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69  alue_text16()] i
31a20 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49  s used, or [SQLI
31a30 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65  TE_UTF8].** othe
31a40 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d  rwise.  ^The sam
31a50 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d  e SQL function m
31a60 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
31a70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
31a80 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65  using.** differe
31a90 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78  nt preferred tex
31aa0 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74  t encodings, wit
31ab0 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c  h different impl
31ac0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a  ementations for.
31ad0 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67  ** each encoding
31ae0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
31af0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
31b00 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
31b10 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
31b20 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
31b30 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
31b40 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
31b50 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
31b60 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
31b70 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rsion..**.** ^Th
31b80 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
31b90 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c  er may optionall
31ba0 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b  y be ORed with [
31bb0 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
31bc0 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e  STIC].** to sign
31bd0 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63  al that the func
31be0 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73  tion will always
31bf0 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
31c00 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a   result given.**
31c10 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73   the same inputs
31c20 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65   within a single
31c30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
31c40 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69   Most SQL functi
31c50 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72  ons are.** deter
31c60 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62  ministic.  The b
31c70 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28  uilt-in [random(
31c80 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  )] SQL function 
31c90 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
31ca0 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74   a.** function t
31cb0 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72  hat is not deter
31cc0 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53  ministic.  The S
31cd0 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e  QLite query plan
31ce0 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a  ner is able to.*
31cf0 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69  * perform additi
31d00 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f  onal optimizatio
31d10 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73  ns on determinis
31d20 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73  tic functions, s
31d30 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20  o use.** of the 
31d40 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
31d50 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72  ISTIC] flag is r
31d60 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65  ecommended where
31d70 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a   possible..**.**
31d80 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
31d90 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
31da0 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
31db0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
31dc0 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
31dd0 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
31de0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
31df0 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
31e00 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
31e10 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  )].)^.**.** ^The
31e20 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20   sixth, seventh 
31e30 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d  and eighth param
31e40 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
31e50 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
31e60 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
31e70 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
31e80 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
31e90 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
31ea0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
31eb0 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
31ec0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
31ed0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
31ee0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
31ef0 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
31f00 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
31f10 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20  ointers must be 
31f20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
31f30 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
31f40 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
31f50 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
31f60 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
31f70 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
31f80 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
31f90 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
31fa0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74  ULL pointer must
31fb0 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
31fc0 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65  Func. ^To delete
31fd0 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
31fe0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
31ff0 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
32000 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f  NULL pointers fo
32010 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
32020 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
32030 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
32040 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  e ninth paramete
32050 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
32060 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
32070 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
32080 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
32090 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
320a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
320b0 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
320c0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
320d0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
320e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
320f0 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
32100 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
32110 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
32120 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32130 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
32140 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
32150 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
32160 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
32170 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
32180 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
32190 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
321a0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
321b0 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
321c0 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
321d0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
321e0 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
321f0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
32200 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
32210 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
32220 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
32230 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
32240 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
32250 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
32260 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
32270 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
32280 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
32290 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
322a0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
322b0 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
322c0 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
322d0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
322e0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
322f0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
32300 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
32310 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
32320 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
32330 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
32340 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
32350 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
32360 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
32370 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
32380 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
32390 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
323a0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
323b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
323c0 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
323d0 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
323e0 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
323f0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
32400 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
32410 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
32420 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
32430 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
32440 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
32450 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
32460 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
32470 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
32480 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
32490 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
324a0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
324b0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
324c0 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
324d0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
324e0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
324f0 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
32500 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
32510 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
32520 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
32530 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
32540 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
32550 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
32560 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
32570 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
32580 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
32590 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
325a0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
325b0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
325c0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ns..**.** ^An ap
325d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
325e0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
325f0 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
32600 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
32610 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
32620 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
32630 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
32640 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
32650 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
32660 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
32670 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
32680 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
32690 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
326a0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
326b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
326c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
326d0 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
326e0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
326f0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
32700 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
32710 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
32720 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
32730 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
32740 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
32750 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
32760 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
32770 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
32780 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
32790 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
327a0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
327b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
327c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
327d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
327e0 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
327f0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
32800 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
32810 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
32820 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
32830 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
32840 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
32850 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32860 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
32870 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
32880 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
32890 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
328a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
328b0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
328c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
328d0 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
328e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
328f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
32900 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
32910 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
32920 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
32930 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
32940 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
32950 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
32960 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
32970 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
32980 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
32990 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
329a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
329b0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
329c0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
329d0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
329e0 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28  ntext*),.  void(
329f0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
32a00 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
32a10 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
32a20 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
32a30 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
32a40 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
32a50 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
32a60 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
32a70 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
32a80 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
32a90 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
32aa0 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
32ab0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
32ac0 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
32ad0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
32ae0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
32af0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
32b00 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
32b10 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
32b20 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
32b30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
32b40 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
32b50 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61   5    /* Depreca
32b60 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ted */.#define S
32b70 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
32b80 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
32b90 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
32ba0 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
32bb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
32bc0 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a  unction Flags.**
32bd0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
32be0 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20  nts may be ORed 
32bf0 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68  together with th
32c00 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  e .** [SQLITE_UT
32c10 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74  F8 | preferred t
32c20 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73  ext encoding] as
32c30 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
32c40 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ment.** to [sqli
32c50 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32c60 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
32c70 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32c80 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
32c90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32ca0 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ction_v2()]..*/.
32cb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
32cc0 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20  ETERMINISTIC    
32cd0 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  0x800../*.** CAP
32ce0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
32cf0 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
32d00 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
32d10 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
32d20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
32d30 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
32d40 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
32d50 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
32d60 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
32d70 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
32d80 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
32d90 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
32da0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
32db0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
32dc0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
32dd0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
32de0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
32df0 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
32e00 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
32e10 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
32e20 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
32e30 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
32e40 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
32e50 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
32e60 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
32e70 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  ED.SQLITE_API SQ
32e80 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
32e90 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
32ea0 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
32eb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
32ec0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
32ed0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
32ee0 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
32ef0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
32f00 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
32f10 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
32f20 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
32f30 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
32f40 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
32f50 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
32f60 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
32f70 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
32f80 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
32f90 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
32fa0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
32fb0 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
32fc0 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
32fd0 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
32fe0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
32ff0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
33000 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
33010 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
33020 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
33030 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
33040 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c         void*,sql
33050 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
33060 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
33070 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
33080 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
33090 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
330a0 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
330b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
330c0 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
330d0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
330e0 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
330f0 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
33100 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
33110 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
33120 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
33130 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
33140 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
33150 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
33160 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
33170 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
33180 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
33190 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
331a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
331b0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
331c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
331d0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
331e0 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
331f0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
33200 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
33210 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
33220 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
33230 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
33240 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
33250 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
33260 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
33270 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
33280 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
33290 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
332a0 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
332b0 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
332c0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
332d0 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
332e0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
332f0 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
33300 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
33310 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
33320 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
33330 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
33340 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
33350 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
33360 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
33370 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
33380 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
33390 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
333a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
333b0 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
333c0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
333d0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
333e0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
333f0 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
33400 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
33410 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
33420 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
33430 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
33440 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
33450 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
33460 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
33470 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
33480 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
33490 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
334a0 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
334b0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
334c0 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
334d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
334e0 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
334f0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
33500 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
33510 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
33520 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
33530 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
33540 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
33550 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
33560 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
33570 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
33580 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
33590 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
335a0 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
335b0 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
335c0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
335d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
335e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
335f0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
33600 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
33610 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
33620 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
33630 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
33640 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
33650 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
33660 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
33670 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
33680 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
33690 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
336a0 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
336b0 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
336c0 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
336d0 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
336e0 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
336f0 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
33700 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
33710 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
33720 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
33730 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
33740 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
33750 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
33760 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
33770 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
33780 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
33790 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
337a0 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
337b0 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
337c0 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
337d0 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
337e0 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
337f0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
33800 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
33810 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
33820 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
33830 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
33840 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
33850 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
33860 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
33870 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
33880 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
33890 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
338a0 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
338b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
338c0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
338d0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
338e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
338f0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
33900 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
33910 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
33920 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
33930 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
33940 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
33950 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
33960 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
33970 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
33980 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
33990 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
339a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
339b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
339c0 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
339d0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
339e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
339f0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
33a00 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
33a10 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c  E_API double sql
33a20 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
33a30 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
33a40 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
33a50 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
33a60 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
33a70 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
33a80 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
33a90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
33aa0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
33ab0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
33ac0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
33ad0 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
33ae0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
33af0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
33b00 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
33b10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33b20 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
33b30 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
33b40 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
33b50 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
33b60 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
33b70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
33b80 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
33b90 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
33ba0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33bb0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
33bc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
33bd0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
33be0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
33bf0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
33c00 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
33c10 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33c20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33c30 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
33c40 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
33c50 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
33c60 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
33c70 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
33c80 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
33c90 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
33ca0 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
33cb0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
33cc0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
33cd0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
33ce0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33cf0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
33d00 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
33d10 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
33d20 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
33d30 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
33d40 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
33d50 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
33d60 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
33d70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
33d80 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
33d90 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
33da0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
33db0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
33dc0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
33dd0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
33de0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
33df0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
33e00 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
33e10 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
33e20 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
33e30 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
33e40 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
33e50 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
33e60 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
33e70 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
33e80 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
33e90 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
33ea0 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
33eb0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
33ec0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
33ed0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
33ee0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
33ef0 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
33f00 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
33f10 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
33f20 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
33f30 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
33f40 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
33f50 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
33f60 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
33f70 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
33f80 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
33f90 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
33fa0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
33fb0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
33fc0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
33fd0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
33fe0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
33ff0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
34000 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
34010 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
34020 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73  er .** when firs
34030 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73  t called if N is
34040 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
34050 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
34060 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  f a memory.** al
34070 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
34080 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
34090 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
340a0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
340b0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
340c0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
340d0 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
340e0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
340f0 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
34100 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
34110 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
34120 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
34130 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
34140 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
34150 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
34160 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
34170 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
34180 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
34190 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
341a0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
341b0 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20  .)^  Within the 
341c0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c  xFinal callback,
341d0 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79   it is customary
341e0 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69   to set.** N=0 i
341f0 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  n calls to sqlit
34200 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
34210 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61  text(C,N) so tha
34220 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65  t no .** pointle
34230 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ss memory alloca
34240 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a  tions occur..**.
34250 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
34260 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
34270 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
34280 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
34290 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
342a0 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
342b0 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
342c0 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
342d0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
342e0 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
342f0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
34300 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
34310 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
34320 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
34330 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
34340 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
34350 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
34360 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
34370 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
34380 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
34390 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
343a0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
343b0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
343c0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
343d0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
343e0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
343f0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
34400 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
34410 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61   void *sqlite3_a
34420 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
34430 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34440 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
34450 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34460 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
34470 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
34480 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
34490 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
344a0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
344b0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
344c0 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
344d0 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
344e0 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
344f0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
34500 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
34510 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
34520 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
34530 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
34540 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
34550 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
34560 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
34570 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
34580 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
34590 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
345a0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
345b0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
345c0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
345d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
345e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
345f0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
34600 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
34610 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
34620 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
34630 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
34640 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
34650 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
34660 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
34670 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
34680 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
34690 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
346a0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
346b0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
346c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
346d0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
346e0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
346f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
34700 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
34710 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
34720 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
34730 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
34740 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
34750 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
34760 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
34770 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
34780 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
34790 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
347a0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
347b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
347c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
347d0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
347e0 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
347f0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
34800 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
34810 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29   (non-aggregate)
34820 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
34830 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
34840 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
34850 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
34860 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
34870 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
34880 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
34890 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
348a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
348b0 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
348c0 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
348d0 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
348e0 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
348f0 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
34900 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20   preserved.  An 
34910 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68  example.** of wh
34920 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62  ere this might b
34930 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61  e useful is in a
34940 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
34950 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20  ion matching.** 
34960 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
34970 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
34980 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
34990 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
349a0 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
349b0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
349c0 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72   with the patter
349d0 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54  n string.  .** T
349e0 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  hen as long as t
349f0 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
34a00 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61  g remains the sa
34a10 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69  me,.** the compi
34a20 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
34a30 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
34a40 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
34a50 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
34a60 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
34a70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
34a80 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
34a90 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
34aa0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
34ab0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
34ac0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
34ad0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
34ae0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
34af0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
34b00 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
34b10 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
34b20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34b30 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74   function. ^If t
34b40 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64  here is no metad
34b50 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
34b60 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74  d with the funct
34b70 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68  ion argument, th
34b80 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  is sqlite3_get_a
34b90 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
34ba0 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ce.** returns a 
34bb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
34bc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34bd0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
34be0 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20  ,P,X) interface 
34bf0 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64  saves P as metad
34c00 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
34c10 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
34c20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34c30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34c40 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a  .  ^Subsequent.*
34c50 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
34c60 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43  e3_get_auxdata(C
34c70 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f  ,N) return P fro
34c80 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  m the most recen
34c90 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  t.** sqlite3_set
34ca0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
34cb0 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65  ) call if the me
34cc0 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20  tadata is still 
34cd0 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c  valid or.** NULL
34ce0 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
34cf0 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72   has been discar
34d00 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65  ded..** ^After e
34d10 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
34d20 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
34d30 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58  C,N,P,X) where X
34d40 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
34d50 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
34d60 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
34d70 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69  or function X wi
34d80 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65  th parameter P e
34d90 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20  xactly.** once, 
34da0 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74  when the metadat
34db0 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a  a is discarded..
34dc0 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
34dd0 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65  e to discard the
34de0 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79   metadata at any
34df0 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67   time, including
34e00 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77  : <ul>.** <li> w
34e10 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
34e20 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
34e30 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
34e40 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  , or.** <li> whe
34e50 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
34e60 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
34e70 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
34e80 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
34e90 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
34ea0 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ent, or.** <li> 
34eb0 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74  when sqlite3_set
34ec0 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e  _auxdata() is in
34ed0 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  voked again on t
34ee0 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65  he same paramete
34ef0 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75  r, or.** <li> du
34f00 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61  ring the origina
34f10 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  l sqlite3_set_au
34f20 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65  xdata() call whe
34f30 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20  n a memory .**  
34f40 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65      allocation e
34f50 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75  rror occurs. </u
34f60 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  l>)^.**.** Note 
34f70 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20  the last bullet 
34f80 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20  in particular.  
34f90 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58  The destructor X
34fa0 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   in .** sqlite3_
34fb0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
34fc0 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61  P,X) might be ca
34fd0 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  lled immediately
34fe0 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20  , before the.** 
34ff0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
35000 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
35010 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48  even returns.  H
35020 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ence sqlite3_set
35030 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68  _auxdata().** sh
35040 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e  ould be called n
35050 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ear the end of t
35060 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
35070 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74  ementation and t
35080 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  he.** function i
35090 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
350a0 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e  ould not make an
350b0 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72  y use of P after
350c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
350d0 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65  auxdata() has be
350e0 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a  en called..**.**
350f0 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
35100 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
35110 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
35120 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
35130 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
35140 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
35150 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f   compile-time co
35160 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69  nstants, includi
35170 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  ng literal.** va
35180 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
35190 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73  ters] and expres
351a0 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66  sions composed f
351b0 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a  rom the same.)^.
351c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
351d0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
351e0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
351f0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
35200 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
35210 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
35220 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
35230 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
35240 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
35250 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
35260 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  N);.SQLITE_API v
35270 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
35280 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
35290 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
352a0 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
352b0 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
352c0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
352d0 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
352e0 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
352f0 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a  r Behavior.**.**
35300 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
35310 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
35320 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
35330 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
35340 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
35350 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
35360 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
35370 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
35380 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72  .  ^If the destr
35390 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
353a0 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
353b0 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
353c0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
353d0 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
353e0 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
353f0 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
35400 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
35410 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
35420 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  ^The.** SQLITE_T
35430 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
35440 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
35450 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
35460 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
35470 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
35480 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
35490 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
354a0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
354b0 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
354c0 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
354d0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
354e0 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
354f0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
35500 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
35510 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
35520 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64  pilers..*/.typed
35530 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
35540 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
35550 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
35560 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
35570 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
35580 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
35590 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
355a0 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
355b0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
355c0 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
355d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
355e0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
355f0 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
35600 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
35610 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
35620 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
35630 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
35640 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
35650 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
35660 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
35670 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
35680 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35690 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
356a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
356b0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
356c0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
356d0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
356e0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
356f0 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
35700 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
35710 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
35720 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
35730 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
35740 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
35750 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
35760 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
35770 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
35780 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
35790 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
357a0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
357b0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
357c0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
357d0 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
357e0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
357f0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
35800 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35810 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
35820 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
35830 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
35840 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
35850 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
35860 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
35870 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
35880 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
35890 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
358a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
358b0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
358c0 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
358d0 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
358e0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
358f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35900 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
35910 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
35920 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
35930 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
35940 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
35950 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
35960 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
35970 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35980 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
35990 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
359a0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
359b0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
359c0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
359d0 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
359e0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
359f0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
35a00 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
35a10 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
35a20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35a30 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
35a40 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
35a50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
35a60 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
35a70 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
35a80 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
35a90 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
35aa0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
35ab0 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
35ac0 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
35ad0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
35ae0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
35af0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
35b00 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
35b10 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
35b20 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
35b30 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
35b40 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
35b50 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
35b60 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
35b70 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
35b80 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
35b90 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
35ba0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
35bb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35bc0 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
35bd0 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
35be0 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
35bf0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
35c00 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
35c10 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
35c20 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
35c30 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
35c40 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
35c50 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
35c60 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
35c70 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
35c80 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
35c90 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
35ca0 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
35cb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
35cc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35cd0 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
35ce0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
35cf0 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
35d00 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
35d10 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
35d20 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
35d30 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
35d40 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
35d50 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
35d60 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
35d70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35d80 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
35d90 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
35da0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
35db0 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
35dc0 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
35dd0 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
35de0 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
35df0 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
35e00 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
35e10 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
35e20 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
35e30 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
35e40 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
35e50 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
35e60 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35e70 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
35e80 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
35e90 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
35ea0 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
35eb0 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
35ec0 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
35ed0 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
35ee0 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
35ef0 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
35f00 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
35f10 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to 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 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
35f40 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
35f50 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
35f60 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
35f70 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
35f80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35f90 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
35fa0 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
35fb0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
35fc0 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
35fd0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
35fe0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
35ff0 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f  B is too long to
36000 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
36010 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
36020 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
36030 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
36040 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
36050 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
36060 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
36070 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
36080 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
36090 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
360a0 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
360b0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
360c0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
360d0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
360e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
360f0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
36100 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
36110 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
36120 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
36130 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
36140 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
36150 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  nt64() interface
36160 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
36170 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
36180 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
36190 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
361a0 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73   be the 64-bit s
361b0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
361c0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
361d0 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
361e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
361f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
36200 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
36210 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
36220 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
36230 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36240 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
36250 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
36260 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36270 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
36280 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
36290 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
362a0 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
362b0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
362c0 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
362d0 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
362e0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
362f0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
36300 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
36310 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
36320 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
36330 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
36340 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
36350 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
36360 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
36370 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
36380 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
36390 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
363a0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65  .** ^SQLite take
363b0 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
363c0 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
363d0 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
363e0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
363f0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
36400 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
36410 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20  erfaces..** ^If 
36420 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
36430 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
36440 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
36450 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
36460 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
36470 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
36480 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
36490 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  2nd parameter.**
364a0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
364b0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
364c0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  r..** ^If the 3r
364d0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
364e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
364f0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
36500 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
36510 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
36520 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
36530 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
36540 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
36550 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
36560 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
36570 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
36580 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
36590 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
365a0 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70  t.  If the 3rd p
365b0 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
365c0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
365d0 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65  t.** must be the
365e0 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74   byte offset int
365f0 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  o the string whe
36600 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
36610 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61  nator would.** a
36620 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72  ppear if the str
36630 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65  ing where NUL te
36640 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
36650 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
36660 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
36670 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74   string at a byt
36680 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73  e offset that is
36690 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76   less than the v
366a0 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a  alue of the 3rd.
366b0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ** parameter, th
366c0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
366d0 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e   string will con
366e0 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
366f0 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65  Ls and the.** re
36700 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
36710 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e  ons operating on
36720 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d   strings with em
36730 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
36740 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66  ndefined..** ^If
36750 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
36760 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
36770 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
36780 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
36790 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
367a0 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
367b0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
367c0 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
367d0 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
367e0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
367f0 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  on the text or B
36800 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20  LOB result when 
36810 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
36820 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
36830 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
36840 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
36850 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
36860 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
36870 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73  faces or to.** s
36880 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
36890 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
368a0 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
368b0 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
368c0 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
368d0 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
368e0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
368f0 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
36900 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
36910 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74  ** copy the cont
36920 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d  ent of the param
36930 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20  eter nor call a 
36940 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
36950 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65  e content.** whe
36960 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
36970 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
36980 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
36990 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
369a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
369b0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
369c0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
369d0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
369e0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
369f0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52  nstant SQLITE_TR
36a00 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20  ANSIENT.** then 
36a10 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
36a20 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c  opy of the resul
36a30 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74  t into space obt
36a40 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72  ained from.** fr
36a50 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
36a60 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20  oc()] before it 
36a70 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
36a80 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36a90 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
36aa0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
36ab0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
36ac0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36ad0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36ae0 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
36af0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
36b00 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
36b10 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
36b20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
36b30 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  r.  ^The.** sqli
36b40 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
36b50 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
36b60 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
36b70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
36b80 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20  .** so that the 
36b90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
36ba0 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
36bb0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
36bc0 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
36bd0 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
36be0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36bf0 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
36c00 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
36c10 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73   ^A [protected s
36c20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
36c30 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
36c40 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
36c50 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
36c60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
36c70 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
36c80 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
36c90 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
36ca0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
36cb0 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
36cc0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
36cd0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
36ce0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
36cf0 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
36d00 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
36d10 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
36d20 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
36d30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
36d40 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
36d50 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
36d60 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
36d70 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
36d80 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
36d90 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53   undefined..*/.S
36da0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
36db0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
36dc0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
36dd0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
36de0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
36df0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
36e00 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
36e10 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
36e20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36e30 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f  double);.SQLITE_
36e40 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
36e50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
36e60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36e70 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
36e80 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
36e90 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36ea0 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
36eb0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
36ec0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53  t void*, int);.S
36ed0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
36ee0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36ef0 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
36f00 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
36f10 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
36f20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36f30 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
36f40 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
36f50 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
36f60 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36f70 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
36f80 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51  ntext*, int);.SQ
36f90 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
36fa0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
36fb0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36fc0 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
36fd0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
36fe0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
36ff0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37000 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
37010 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
37020 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
37030 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ull(sqlite3_cont
37040 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
37050 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
37060 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
37070 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
37080 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
37090 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
370a0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
370b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
370c0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
370d0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
370e0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
370f0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
37100 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
37110 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
37120 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
37130 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
37140 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
37150 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
37160 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
37170 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
37180 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37190 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
371a0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
371b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
371c0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
371d0 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
371e0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
371f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
37200 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
37210 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
37220 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
37230 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
37240 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
37250 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
37260 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a  ng Sequences.**.
37270 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
37280 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c  ons add, remove,
37290 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f   or modify a [co
372a0 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  llation] associa
372b0 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
372c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
372d0 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
372e0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
372f0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
37300 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
37310 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46  llation is a UTF
37320 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
37330 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37340 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
37350 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37360 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
37370 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
37380 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
37390 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71  yte order for sq
373a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
373b0 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e  lation16()..** ^
373c0 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20  Collation names 
373d0 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75  that compare equ
373e0 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  al according to 
373f0 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d  [sqlite3_strnicm
37400 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  p()] are.** cons
37410 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65  idered to be the
37420 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a   same name..**.*
37430 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72  * ^(The third ar
37440 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70  gument (eTextRep
37450 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
37460 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a   the constants:.
37470 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
37480 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
37490 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
374a0 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16LE],.** <li>
374b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
374c0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
374d0 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a  TE_UTF16], or.**
374e0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
374f0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a  F16_ALIGNED]..**
37500 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65   </ul>)^.** ^The
37510 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
37520 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  nt determines th
37530 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74  e encoding of st
37540 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20  rings passed.** 
37550 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
37560 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
37570 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a  ck, xCallback..*
37580 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
37590 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54  TF16] and [SQLIT
375a0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
375b0 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78   values for eTex
375c0 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74  tRep.** force st
375d0 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31  rings to be UTF1
375e0 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79  6 with native by
375f0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68  te order..** ^Th
37600 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
37610 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66  ALIGNED] value f
37620 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63  or eTextRep forc
37630 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  es strings to be
37640 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65  gin.** on an eve
37650 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a  n byte address..
37660 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
37670 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67  h argument, pArg
37680 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74  , is an applicat
37690 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
376a0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a   that is passed.
376b0 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ** through as th
376c0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
376d0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
376e0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
376f0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
37700 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  fifth argument, 
37710 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20  xCallback, is a 
37720 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
37730 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
37740 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20  n..** ^Multiple 
37750 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37760 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73  ons can be regis
37770 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
37780 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a  same name but.**
37790 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
377a0 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74  eTextRep paramet
377b0 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77  ers and SQLite w
377c0 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65  ill use whicheve
377d0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  r.** function re
377e0 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
377f0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
37800 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a  transformation..
37810 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c  ** ^If the xCall
37820 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
37830 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
37840 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
37850 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e  n is.** deleted.
37860 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c    ^When all coll
37870 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
37880 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20  having the same 
37890 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64  name are deleted
378a0 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74  ,.** that collat
378b0 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ion is no longer
378c0 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e   usable..**.** ^
378d0 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
378e0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20  nction callback 
378f0 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
37900 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41  a copy of the pA
37910 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  rg .** applicati
37920 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
37930 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72  and with two str
37940 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f  ings in the enco
37950 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a  ding specified.*
37960 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65  * by the eTextRe
37970 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65  p argument.  The
37980 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37990 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20  ion must return 
379a0 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68  an.** integer th
379b0 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  at is negative, 
379c0 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76  zero, or positiv
379d0 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73  e.** if the firs
379e0 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
379f0 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c   than, equal to,
37a00 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
37a10 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20   the second,.** 
37a20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41  respectively.  A
37a30 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37a40 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ion must always 
37a50 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
37a60 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20  answer.** given 
37a70 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e  the same inputs.
37a80 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65    If two or more
37a90 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37aa0 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65  ions are registe
37ab0 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  red.** to the sa
37ac0 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  me collation nam
37ad0 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65  e (using differe
37ae0 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75  nt eTextRep valu
37af0 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20  es) then all.** 
37b00 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75  must give an equ
37b10 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77  ivalent answer w
37b20 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68  hen invoked with
37b30 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69   equivalent stri
37b40 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c  ngs..** The coll
37b50 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
37b60 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c  ust obey the fol
37b70 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65  lowing propertie
37b80 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72  s for all.** str
37b90 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43  ings A, B, and C
37ba0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
37bb0 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65  <li> If A==B the
37bc0 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  n B==A..** <li> 
37bd0 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43  If A==B and B==C
37be0 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c   then A==C..** <
37bf0 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48  li> If A&lt;B TH
37c00 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c  EN B&gt;A..** <l
37c10 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64  i> If A&lt;B and
37c20 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c   B&lt;C then A&l
37c30 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  t;C..** </ol>.**
37c40 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69  .** If a collati
37c50 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  ng function fail
37c60 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f  s any of the abo
37c70 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  ve constraints a
37c80 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61  nd that.** colla
37c90 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
37ca0 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64    registered and
37cb0 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
37cc0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
37cd0 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  te.** is undefin
37ce0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
37cf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37d00 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
37d10 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
37d20 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
37d30 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61  ().** with the a
37d40 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65  ddition that the
37d50 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
37d60 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
37d70 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68   pArg when.** th
37d80 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
37d90 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e  tion is deleted.
37da0 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66  .** ^Collating f
37db0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c  unctions are del
37dc0 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  eted when they a
37dd0 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
37de0 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20   later.** calls 
37df0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  to the collation
37e00 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
37e10 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a  ons or when the.
37e20 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
37e30 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73  nection] is clos
37e40 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
37e50 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
37e60 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20  * ^The xDestroy 
37e70 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e  callback is <u>n
37e80 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66  ot</u> called if
37e90 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   the .** sqlite3
37ea0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37eb0 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20  n_v2() function 
37ec0 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74  fails.  Applicat
37ed0 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65  ions that invoke
37ee0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
37ef0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
37f00 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  ) with a non-NUL
37f10 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d  L xDestroy argum
37f20 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63  ent should .** c
37f30 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
37f40 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65  code and dispose
37f50 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
37f60 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
37f70 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72  .** themselves r
37f80 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63  ather than expec
37f90 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64  ting SQLite to d
37fa0 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20  eal with it for 
37fb0 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73  them..** This is
37fc0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
37fd0 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69  every other SQLi
37fe0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  te interface.  T
37ff0 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79  he inconsistency
38000 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e   .** is unfortun
38010 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62  ate but cannot b
38020 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75  e changed withou
38030 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77  t breaking backw
38040 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69  ards .** compati
38050 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  bility..**.** Se
38060 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65  e also:  [sqlite
38070 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
38080 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ed()] and [sqlit
38090 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
380a0 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ded16()]..*/.SQL
380b0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
380c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
380d0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
380e0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
380f0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
38100 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
38110 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
38120 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
38130 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
38140 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
38150 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
38160 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
38170 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
38180 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
38190 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
381a0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
381b0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
381c0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
381d0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
381e0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
381f0 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
38200 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
38210 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
38220 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
38230 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
38240 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
38250 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
38260 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
38270 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
38280 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
38290 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
382a0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
382b0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
382c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
382d0 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
382e0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
382f0 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20  To avoid having 
38300 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20  to register all 
38310 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
38320 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74  ces before a dat
38330 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20  abase.** can be 
38340 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63  used, a single c
38350 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
38360 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
38370 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
38380 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
38390 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b  ion] to be invok
383a0 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
383b0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
383c0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69  on.** sequence i
383d0 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
383e0 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  * ^If the functi
383f0 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
38400 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
38410 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
38420 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68  ded() API,.** th
38430 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20  en it is passed 
38440 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64  the names of und
38450 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
38460 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74   sequences as st
38470 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64  rings.** encoded
38480 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73   in UTF-8. ^If s
38490 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
384a0 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
384b0 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  sed,.** the name
384c0 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  s are passed as 
384d0 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
384e0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
384f0 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  der..** ^A call 
38500 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69  to either functi
38510 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20  on replaces the 
38520 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69  existing collati
38530 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61  on-needed callba
38540 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e  ck..**.** ^(When
38550 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
38560 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
38570 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
38580 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
38590 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
385a0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
385b0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
385c0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
385d0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
385e0 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
385f0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
38600 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
38610 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
38620 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
38630 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
38640 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
38650 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
38660 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
38670 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
38680 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
38690 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
386a0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
386b0 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
386c0 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
386d0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
386e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
386f0 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
38700 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
38710 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  )^.**.** The cal
38720 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
38730 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74  hould register t
38740 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61  he desired colla
38750 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
38760 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
38770 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  llation()], [sql
38780 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c