System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact bb0bab470bfa199ed083aa99a001c39c167a0215:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  ** This file is 
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20  an amalgamation 
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65  of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20   C source files 
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76  from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 37 2e 36 2e 33 2e 20  ersion 3.7.6.3. 
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 53  mit LFS..**.** S
0b00: 69 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20 66  imilar is true f
0b10: 6f 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46  or Mac OS X.  LF
0b20: 53 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72  S is only suppor
0b30: 74 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20  ted on Mac OS X 
0b40: 39 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a  9 and later..*/.
0b50: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44  #ifndef SQLITE_D
0b60: 49 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66  ISABLE_LFS.# def
0b70: 69 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20  ine _LARGE_FILE 
0b80: 20 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66        1.# ifndef
0b90: 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49   _FILE_OFFSET_BI
0ba0: 54 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46  TS.#   define _F
0bb0: 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20  ILE_OFFSET_BITS 
0bc0: 36 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66  64.# endif.# def
0bd0: 69 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53  ine _LARGEFILE_S
0be0: 4f 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a  OURCE 1.#endif..
0bf0: 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68  /*.** Include th
0c00: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
0c10: 68 65 61 64 65 72 20 6f 75 74 70 75 74 20 62 79  header output by
0c20: 20 27 63 6f 6e 66 69 67 75 72 65 27 20 69 66 20   'configure' if 
0c30: 77 65 27 72 65 20 75 73 69 6e 67 20 74 68 65 0a  we're using the.
0c40: 2a 2a 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73 65  ** autoconf-base
0c50: 64 20 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64 65  d build.*/.#ifde
0c60: 66 20 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f 43  f _HAVE_SQLITE_C
0c70: 4f 4e 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64 65  ONFIG_H.#include
0c80: 20 22 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e 64   "config.h".#end
0c90: 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  if../***********
0ca0: 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69  *** Include sqli
0cb0: 74 65 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68 65  teLimit.h in the
0cc0: 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74   middle of sqlit
0cd0: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
0ce0: 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  **/./***********
0cf0: 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73  *** Begin file s
0d00: 71 6c 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a 2a  qliteLimit.h ***
0d10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d30: 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20 4d  **/./*.** 2007 M
0d40: 61 79 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ay 7.**.** The a
0d50: 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20  uthor disclaims 
0d60: 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69  copyright to thi
0d70: 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
0d80: 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61  In place of.** a
0d90: 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68   legal notice, h
0da0: 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e  ere is a blessin
0db0: 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20  g:.**.**    May 
0dc0: 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20  you do good and 
0dd0: 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20  not evil..**    
0de0: 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72  May you find for
0df0: 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75  giveness for you
0e00: 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76  rself and forgiv
0e10: 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20  e others..**    
0e20: 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72  May you share fr
0e30: 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69  eely, never taki
0e40: 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75  ng more than you
0e50: 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a   give..**.******
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ea0: 2a 2a 2a 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73 20  ***.** .** This 
0eb0: 66 69 6c 65 20 64 65 66 69 6e 65 73 20 76 61 72  file defines var
0ec0: 69 6f 75 73 20 6c 69 6d 69 74 73 20 6f 66 20 77  ious limits of w
0ed0: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 70  hat SQLite can p
0ee0: 72 6f 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a  rocess..*/../*.*
0ef0: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  * The maximum le
0f00: 6e 67 74 68 20 6f 66 20 61 20 54 45 58 54 20 6f  ngth of a TEXT o
0f10: 72 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e  r BLOB in bytes.
0f20: 20 20 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a 20     This also.** 
0f30: 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20  limits the size 
0f40: 6f 66 20 61 20 72 6f 77 20 69 6e 20 61 20 74 61  of a row in a ta
0f50: 62 6c 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a 2a  ble or index..**
0f60: 0a 2a 2a 20 54 68 65 20 68 61 72 64 20 6c 69 6d  .** The hard lim
0f70: 69 74 20 69 73 20 74 68 65 20 61 62 69 6c 69 74  it is the abilit
0f80: 79 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69  y of a 32-bit si
0f90: 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
0fa0: 74 6f 20 63 6f 75 6e 74 20 74 68 65 20 73 69 7a  to count the siz
0fb0: 65 3a 20 32 5e 33 31 2d 31 20 6f 72 20 32 31 34  e: 2^31-1 or 214
0fc0: 37 34 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66 6e  7483647..*/.#ifn
0fd0: 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c  def SQLITE_MAX_L
0fe0: 45 4e 47 54 48 0a 23 20 64 65 66 69 6e 65 20 53  ENGTH.# define S
0ff0: 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48  QLITE_MAX_LENGTH
1000: 20 31 30 30 30 30 30 30 30 30 30 0a 23 65 6e 64   1000000000.#end
1010: 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 69  if../*.** This i
1020: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  s the maximum nu
1030: 6d 62 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20 20  mber of.**.**   
1040: 20 2a 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61 20   * Columns in a 
1050: 74 61 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43 6f  table.**    * Co
1060: 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
1070: 78 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d 6e  x.**    * Column
1080: 73 20 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20 20  s in a view.**  
1090: 20 20 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65    * Terms in the
10a0: 20 53 45 54 20 63 6c 61 75 73 65 20 6f 66 20 61   SET clause of a
10b0: 6e 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  n UPDATE stateme
10c0: 6e 74 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73  nt.**    * Terms
10d0: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
10e0: 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73  et of a SELECT s
10f0: 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 2a  tatement.**    *
1100: 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20 47 52   Terms in the GR
1110: 4f 55 50 20 42 59 20 6f 72 20 4f 52 44 45 52 20  OUP BY or ORDER 
1120: 42 59 20 63 6c 61 75 73 65 73 20 6f 66 20 61 20  BY clauses of a 
1130: 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
1140: 2e 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20  ..**    * Terms 
1150: 69 6e 20 74 68 65 20 56 41 4c 55 45 53 20 63 6c  in the VALUES cl
1160: 61 75 73 65 20 6f 66 20 61 6e 20 49 4e 53 45 52  ause of an INSER
1170: 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  T statement.**.*
1180: 2a 20 54 68 65 20 68 61 72 64 20 75 70 70 65 72  * The hard upper
1190: 20 6c 69 6d 69 74 20 68 65 72 65 20 69 73 20 33   limit here is 3
11a0: 32 36 37 36 2e 20 20 4d 6f 73 74 20 64 61 74 61  2676.  Most data
11b0: 62 61 73 65 20 70 65 6f 70 6c 65 20 77 69 6c 6c  base people will
11c0: 0a 2a 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68 61  .** tell you tha
11d0: 74 20 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72 6d  t in a well-norm
11e0: 61 6c 69 7a 65 64 20 64 61 74 61 62 61 73 65 2c  alized database,
11f0: 20 79 6f 75 20 75 73 75 61 6c 6c 79 20 73 68 6f   you usually sho
1200: 75 6c 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65 20  uld.** not have 
1210: 6d 6f 72 65 20 74 68 61 6e 20 61 20 64 6f 7a 65  more than a doze
1220: 6e 20 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73 20  n or so columns 
1230: 69 6e 20 61 6e 79 20 74 61 62 6c 65 2e 20 20 41  in any table.  A
1240: 6e 64 20 69 66 0a 2a 2a 20 74 68 61 74 20 69 73  nd if.** that is
1250: 20 74 68 65 20 63 61 73 65 2c 20 74 68 65 72 65   the case, there
1260: 20 69 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20   is no point in 
1270: 68 61 76 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e  having more than
1280: 20 61 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e 20   a few.** dozen 
1290: 76 61 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f 66  values in any of
12a0: 20 74 68 65 20 6f 74 68 65 72 20 73 69 74 75 61   the other situa
12b0: 74 69 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20  tions described 
12c0: 61 62 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65  above..*/.#ifnde
12d0: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c  f SQLITE_MAX_COL
12e0: 55 4d 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  UMN.# define SQL
12f0: 49 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20 32  ITE_MAX_COLUMN 2
1300: 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  000.#endif../*.*
1310: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  * The maximum le
1320: 6e 67 74 68 20 6f 66 20 61 20 73 69 6e 67 6c 65  ngth of a single
1330: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1340: 6e 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49  n bytes..**.** I
1350: 74 20 75 73 65 64 20 74 6f 20 62 65 20 74 68 65  t used to be the
1360: 20 63 61 73 65 20 74 68 61 74 20 73 65 74 74 69   case that setti
1370: 6e 67 20 74 68 69 73 20 76 61 6c 75 65 20 74 6f  ng this value to
1380: 20 7a 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20 74   zero would.** t
1390: 75 72 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f 66  urn the limit of
13a0: 66 2e 20 20 54 68 61 74 20 69 73 20 6e 6f 20 6c  f.  That is no l
13b0: 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 49 74 20  onger true.  It 
13c0: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 0a  is not possible.
13d0: 2a 2a 20 74 6f 20 74 75 72 6e 20 74 68 69 73 20  ** to turn this 
13e0: 6c 69 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23 69  limit off..*/.#i
13f0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58  fndef SQLITE_MAX
1400: 5f 53 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64 65  _SQL_LENGTH.# de
1410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f  fine SQLITE_MAX_
1420: 53 51 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30 30  SQL_LENGTH 10000
1430: 30 30 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a  00000.#endif../*
1440: 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20  .** The maximum 
1450: 64 65 70 74 68 20 6f 66 20 61 6e 20 65 78 70 72  depth of an expr
1460: 65 73 73 69 6f 6e 20 74 72 65 65 2e 20 54 68 69  ession tree. Thi
1470: 73 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  s is limited to 
1480: 0a 2a 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74 20  .** some extent 
1490: 62 79 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51  by SQLITE_MAX_SQ
14a0: 4c 5f 4c 45 4e 47 54 48 2e 20 42 75 74 20 73 6f  L_LENGTH. But so
14b0: 6d 65 74 69 6d 65 20 79 6f 75 20 6d 69 67 68 74  metime you might
14c0: 20 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c 61   .** want to pla
14d0: 63 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 6c  ce more severe l
14e0: 69 6d 69 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d  imits on the com
14f0: 70 6c 65 78 69 74 79 20 6f 66 20 61 6e 20 0a 2a  plexity of an .*
1500: 2a 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a 2a  * expression..**
1510: 0a 2a 2a 20 41 20 76 61 6c 75 65 20 6f 66 20 30  .** A value of 0
1520: 20 75 73 65 64 20 74 6f 20 6d 65 61 6e 20 74 68   used to mean th
1530: 61 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73  at the limit was
1540: 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a 2a   not enforced..*
1550: 2a 20 42 75 74 20 74 68 61 74 20 69 73 20 6e 6f  * But that is no
1560: 20 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 54   longer true.  T
1570: 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77 20  he limit is now 
1580: 73 74 72 69 63 74 6c 79 20 65 6e 66 6f 72 63 65  strictly enforce
1590: 64 0a 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d 65  d.** at all time
15a0: 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  s..*/.#ifndef SQ
15b0: 4c 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45  LITE_MAX_EXPR_DE
15c0: 50 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  PTH.# define SQL
15d0: 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50  ITE_MAX_EXPR_DEP
15e0: 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a  TH 1000.#endif..
15f0: 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75  /*.** The maximu
1600: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
1610: 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
1620: 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
1630: 2e 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 67 65  ..** The code ge
1640: 6e 65 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d 70  nerator for comp
1650: 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
1660: 65 6d 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65 0a  ements does one.
1670: 2a 2a 20 6c 65 76 65 6c 20 6f 66 20 72 65 63 75  ** level of recu
1680: 72 73 69 6f 6e 20 66 6f 72 20 65 61 63 68 20 74  rsion for each t
1690: 65 72 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f 76  erm.  A stack ov
16a0: 65 72 66 6c 6f 77 20 63 61 6e 20 72 65 73 75 6c  erflow can resul
16b0: 74 0a 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d 62  t.** if the numb
16c0: 65 72 20 6f 66 20 74 65 72 6d 73 20 69 73 20 74  er of terms is t
16d0: 6f 6f 20 6c 61 72 67 65 2e 20 20 49 6e 20 70 72  oo large.  In pr
16e0: 61 63 74 69 63 65 2c 20 6d 6f 73 74 20 53 51 4c  actice, most SQL
16f0: 0a 2a 2a 20 6e 65 76 65 72 20 68 61 73 20 6d 6f  .** never has mo
1700: 72 65 20 74 68 61 6e 20 33 20 6f 72 20 34 20 74  re than 3 or 4 t
1710: 65 72 6d 73 2e 20 20 55 73 65 20 61 20 76 61 6c  erms.  Use a val
1720: 75 65 20 6f 66 20 30 20 74 6f 20 64 69 73 61 62  ue of 0 to disab
1730: 6c 65 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74 20  le.** any limit 
1740: 6f 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  on the number of
1750: 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
1760: 6f 75 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f 0a  ount SELECT..*/.
1770: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  #ifndef SQLITE_M
1780: 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  AX_COMPOUND_SELE
1790: 43 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CT.# define SQLI
17a0: 54 45 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f  TE_MAX_COMPOUND_
17b0: 53 45 4c 45 43 54 20 35 30 30 0a 23 65 6e 64 69  SELECT 500.#endi
17c0: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78  f../*.** The max
17d0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 6f  imum number of o
17e0: 70 63 6f 64 65 73 20 69 6e 20 61 20 56 44 42 45  pcodes in a VDBE
17f0: 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f 74   program..** Not
1800: 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f 72   currently enfor
1810: 63 65 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ced..*/.#ifndef 
1820: 53 51 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f  SQLITE_MAX_VDBE_
1830: 4f 50 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  OP.# define SQLI
1840: 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20 32  TE_MAX_VDBE_OP 2
1850: 35 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  5000.#endif../*.
1860: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  ** The maximum n
1870: 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
1880: 74 73 20 74 6f 20 61 6e 20 53 51 4c 20 66 75 6e  ts to an SQL fun
1890: 63 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ction..*/.#ifnde
18a0: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e  f SQLITE_MAX_FUN
18b0: 43 54 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66 69  CTION_ARG.# defi
18c0: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55  ne SQLITE_MAX_FU
18d0: 4e 43 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a 23  NCTION_ARG 127.#
18e0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  endif../*.** The
18f0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1900: 6f 66 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61 67  of in-memory pag
1910: 65 73 20 74 6f 20 75 73 65 20 66 6f 72 20 74 68  es to use for th
1920: 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 0a  e main database.
1930: 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 66 6f 72  ** table and for
1940: 20 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c 65   temporary table
1950: 73 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 44  s.  The SQLITE_D
1960: 45 46 41 55 4c 54 5f 43 41 43 48 45 5f 53 49 5a  EFAULT_CACHE_SIZ
1970: 45 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  E.*/.#ifndef SQL
1980: 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43 48  ITE_DEFAULT_CACH
1990: 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20  E_SIZE.# define 
19a0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43  SQLITE_DEFAULT_C
19b0: 41 43 48 45 5f 53 49 5a 45 20 20 32 30 30 30 0a  ACHE_SIZE  2000.
19c0: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
19d0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 54 45  QLITE_DEFAULT_TE
19e0: 4d 50 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23 20  MP_CACHE_SIZE.# 
19f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1a00: 46 41 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48 45  FAULT_TEMP_CACHE
1a10: 5f 53 49 5a 45 20 20 35 30 30 0a 23 65 6e 64 69  _SIZE  500.#endi
1a20: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66  f../*.** The def
1a30: 61 75 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20 66  ault number of f
1a40: 72 61 6d 65 73 20 74 6f 20 61 63 63 75 6d 75 6c  rames to accumul
1a50: 61 74 65 20 69 6e 20 74 68 65 20 6c 6f 67 20 66  ate in the log f
1a60: 69 6c 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63 68  ile before.** ch
1a70: 65 63 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65 20  eckpointing the 
1a80: 64 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c 20  database in WAL 
1a90: 6d 6f 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  mode..*/.#ifndef
1aa0: 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f   SQLITE_DEFAULT_
1ab0: 57 41 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49  WAL_AUTOCHECKPOI
1ac0: 4e 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  NT.# define SQLI
1ad0: 54 45 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f 41  TE_DEFAULT_WAL_A
1ae0: 55 54 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20 31  UTOCHECKPOINT  1
1af0: 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  000.#endif../*.*
1b00: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  * The maximum nu
1b10: 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64  mber of attached
1b20: 20 64 61 74 61 62 61 73 65 73 2e 20 20 54 68 69   databases.  Thi
1b30: 73 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  s must be betwee
1b40: 6e 20 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20 20  n 0.** and 62.  
1b50: 54 68 65 20 75 70 70 65 72 20 62 6f 75 6e 64 20  The upper bound 
1b60: 6f 6e 20 36 32 20 69 73 20 62 65 63 61 75 73 65  on 62 is because
1b70: 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65   a 64-bit intege
1b80: 72 20 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20 75  r bitmap.** is u
1b90: 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
1ba0: 6f 20 74 72 61 63 6b 20 61 74 74 61 63 68 65 64  o track attached
1bb0: 20 64 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a 23   databases..*/.#
1bc0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41  ifndef SQLITE_MA
1bd0: 58 5f 41 54 54 41 43 48 45 44 0a 23 20 64 65 66  X_ATTACHED.# def
1be0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 41  ine SQLITE_MAX_A
1bf0: 54 54 41 43 48 45 44 20 31 30 0a 23 65 6e 64 69  TTACHED 10.#endi
1c00: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61  f.../*.** The ma
1c10: 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 61  ximum value of a
1c20: 20 3f 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20 74   ?nnn wildcard t
1c30: 68 61 74 20 74 68 65 20 70 61 72 73 65 72 20 77  hat the parser w
1c40: 69 6c 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a 23  ill accept..*/.#
1c50: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41  ifndef SQLITE_MA
1c60: 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  X_VARIABLE_NUMBE
1c70: 52 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  R.# define SQLIT
1c80: 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e  E_MAX_VARIABLE_N
1c90: 55 4d 42 45 52 20 39 39 39 0a 23 65 6e 64 69 66  UMBER 999.#endif
1ca0: 0a 0a 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61 67  ../* Maximum pag
1cb0: 65 20 73 69 7a 65 2e 20 20 54 68 65 20 75 70 70  e size.  The upp
1cc0: 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69 73  er bound on this
1cd0: 20 76 61 6c 75 65 20 69 73 20 36 35 35 33 36 2e   value is 65536.
1ce0: 20 20 54 68 69 73 20 61 20 6c 69 6d 69 74 0a 2a    This a limit.*
1cf0: 2a 20 69 6d 70 6f 73 65 64 20 62 79 20 74 68 65  * imposed by the
1d00: 20 75 73 65 20 6f 66 20 31 36 2d 62 69 74 20 6f   use of 16-bit o
1d10: 66 66 73 65 74 73 20 77 69 74 68 69 6e 20 65 61  ffsets within ea
1d20: 63 68 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 45  ch page..**.** E
1d30: 61 72 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 20  arlier versions 
1d40: 6f 66 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 65  of SQLite allowe
1d50: 64 20 74 68 65 20 75 73 65 72 20 74 6f 20 63 68  d the user to ch
1d60: 61 6e 67 65 20 74 68 69 73 20 76 61 6c 75 65 20  ange this value 
1d70: 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69  at.** compile ti
1d80: 6d 65 2e 20 54 68 69 73 20 69 73 20 6e 6f 20 6c  me. This is no l
1d90: 6f 6e 67 65 72 20 70 65 72 6d 69 74 74 65 64 2c  onger permitted,
1da0: 20 6f 6e 20 74 68 65 20 67 72 6f 75 6e 64 73 20   on the grounds 
1db0: 74 68 61 74 20 69 74 20 63 72 65 61 74 65 73 0a  that it creates.
1dc0: 2a 2a 20 61 20 6c 69 62 72 61 72 79 20 74 68 61  ** a library tha
1dd0: 74 20 69 73 20 74 65 63 68 6e 69 63 61 6c 6c 79  t is technically
1de0: 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 69   incompatible wi
1df0: 74 68 20 61 6e 20 53 51 4c 69 74 65 20 6c 69 62  th an SQLite lib
1e00: 72 61 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  rary .** compile
1e10: 64 20 77 69 74 68 20 61 20 64 69 66 66 65 72 65  d with a differe
1e20: 6e 74 20 6c 69 6d 69 74 2e 20 49 66 20 61 20 70  nt limit. If a p
1e30: 72 6f 63 65 73 73 20 6f 70 65 72 61 74 69 6e 67  rocess operating
1e40: 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 0a   on a database .
1e50: 2a 2a 20 77 69 74 68 20 61 20 70 61 67 65 2d 73  ** with a page-s
1e60: 69 7a 65 20 6f 66 20 36 35 35 33 36 20 62 79 74  ize of 65536 byt
1e70: 65 73 20 63 72 61 73 68 65 73 2c 20 74 68 65 6e  es crashes, then
1e80: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
1e90: 53 51 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70 69  SQLite .** compi
1ea0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 64 65 66  led with the def
1eb0: 61 75 6c 74 20 70 61 67 65 2d 73 69 7a 65 20 6c  ault page-size l
1ec0: 69 6d 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62 65  imit will not be
1ed0: 20 61 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61 63   able to rollbac
1ee0: 6b 20 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74 65  k .** the aborte
1ef0: 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54  d transaction. T
1f00: 68 69 73 20 63 6f 75 6c 64 20 6c 65 61 64 20 74  his could lead t
1f10: 6f 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  o database corru
1f20: 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65 66  ption..*/.#ifdef
1f30: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45   SQLITE_MAX_PAGE
1f40: 5f 53 49 5a 45 0a 23 20 75 6e 64 65 66 20 53 51  _SIZE.# undef SQ
1f50: 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49  LITE_MAX_PAGE_SI
1f60: 5a 45 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e  ZE.#endif.#defin
1f70: 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47  e SQLITE_MAX_PAG
1f80: 45 5f 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a 2f  E_SIZE 65536.../
1f90: 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
1fa0: 20 73 69 7a 65 20 6f 66 20 61 20 64 61 74 61 62   size of a datab
1fb0: 61 73 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69 66  ase page..*/.#if
1fc0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41  ndef SQLITE_DEFA
1fd0: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20  ULT_PAGE_SIZE.# 
1fe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1ff0: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20  FAULT_PAGE_SIZE 
2000: 31 30 32 34 0a 23 65 6e 64 69 66 0a 23 69 66 20  1024.#endif.#if 
2010: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50  SQLITE_DEFAULT_P
2020: 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45 5f  AGE_SIZE>SQLITE_
2030: 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20  MAX_PAGE_SIZE.# 
2040: 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46  undef SQLITE_DEF
2050: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23  AULT_PAGE_SIZE.#
2060: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44   define SQLITE_D
2070: 45 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45  EFAULT_PAGE_SIZE
2080: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45   SQLITE_MAX_PAGE
2090: 5f 53 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a  _SIZE.#endif../*
20a0: 0a 2a 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c 20  .** Ordinarily, 
20b0: 69 66 20 6e 6f 20 76 61 6c 75 65 20 69 73 20 65  if no value is e
20c0: 78 70 6c 69 63 69 74 6c 79 20 70 72 6f 76 69 64  xplicitly provid
20d0: 65 64 2c 20 53 51 4c 69 74 65 20 63 72 65 61 74  ed, SQLite creat
20e0: 65 73 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20  es databases.** 
20f0: 77 69 74 68 20 70 61 67 65 20 73 69 7a 65 20 53  with page size S
2100: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41  QLITE_DEFAULT_PA
2110: 47 45 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65 72  GE_SIZE. However
2120: 2c 20 62 61 73 65 64 20 6f 6e 20 63 65 72 74 61  , based on certa
2130: 69 6e 0a 2a 2a 20 64 65 76 69 63 65 20 63 68 61  in.** device cha
2140: 72 61 63 74 65 72 69 73 74 69 63 73 20 28 73 65  racteristics (se
2150: 63 74 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61 74  ctor-size and at
2160: 6f 6d 69 63 20 77 72 69 74 65 28 29 20 73 75 70  omic write() sup
2170: 70 6f 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74 65  port),.** SQLite
2180: 20 6d 61 79 20 63 68 6f 6f 73 65 20 61 20 6c 61   may choose a la
2190: 72 67 65 72 20 76 61 6c 75 65 2e 20 54 68 69 73  rger value. This
21a0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 74 68 65   constant is the
21b0: 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a 2a   maximum value.*
21c0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 68  * SQLite will ch
21d0: 6f 6f 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e 2e  oose on its own.
21e0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
21f0: 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50  TE_MAX_DEFAULT_P
2200: 41 47 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e  AGE_SIZE.# defin
2210: 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46  e SQLITE_MAX_DEF
2220: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 38  AULT_PAGE_SIZE 8
2230: 31 39 32 0a 23 65 6e 64 69 66 0a 23 69 66 20 53  192.#endif.#if S
2240: 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c  QLITE_MAX_DEFAUL
2250: 54 5f 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49  T_PAGE_SIZE>SQLI
2260: 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45  TE_MAX_PAGE_SIZE
2270: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
2280: 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 45  MAX_DEFAULT_PAGE
2290: 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53  _SIZE.# define S
22a0: 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c  QLITE_MAX_DEFAUL
22b0: 54 5f 50 41 47 45 5f 53 49 5a 45 20 53 51 4c 49  T_PAGE_SIZE SQLI
22c0: 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45  TE_MAX_PAGE_SIZE
22d0: 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20  .#endif.../*.** 
22e0: 4d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  Maximum number o
22f0: 66 20 70 61 67 65 73 20 69 6e 20 6f 6e 65 20 64  f pages in one d
2300: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
2310: 0a 2a 2a 20 54 68 69 73 20 69 73 20 72 65 61 6c  .** This is real
2320: 6c 79 20 6a 75 73 74 20 74 68 65 20 64 65 66 61  ly just the defa
2330: 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ult value for th
2340: 65 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74  e max_page_count
2350: 20 70 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69 73   pragma..** This
2360: 20 76 61 6c 75 65 20 63 61 6e 20 62 65 20 6c 6f   value can be lo
2370: 77 65 72 65 64 20 28 6f 72 20 72 61 69 73 65 64  wered (or raised
2380: 29 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  ) at run-time us
2390: 69 6e 67 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ing that the.** 
23a0: 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 6d  max_page_count m
23b0: 61 63 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  acro..*/.#ifndef
23c0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45   SQLITE_MAX_PAGE
23d0: 5f 43 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65 20  _COUNT.# define 
23e0: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
23f0: 43 4f 55 4e 54 20 31 30 37 33 37 34 31 38 32 33  COUNT 1073741823
2400: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d  .#endif../*.** M
2410: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28 69  aximum length (i
2420: 6e 20 62 79 74 65 73 29 20 6f 66 20 74 68 65 20  n bytes) of the 
2430: 70 61 74 74 65 72 6e 20 69 6e 20 61 20 4c 49 4b  pattern in a LIK
2440: 45 20 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70 65  E or GLOB.** ope
2450: 72 61 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65  rator..*/.#ifnde
2460: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49 4b  f SQLITE_MAX_LIK
2470: 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
2480: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2490: 5f 4d 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45 52  _MAX_LIKE_PATTER
24a0: 4e 5f 4c 45 4e 47 54 48 20 35 30 30 30 30 0a 23  N_LENGTH 50000.#
24b0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78  endif../*.** Max
24c0: 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
24d0: 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
24e0: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 61  gers..**.** A va
24f0: 6c 75 65 20 6f 66 20 31 20 6d 65 61 6e 73 20 74  lue of 1 means t
2500: 68 61 74 20 61 20 74 72 69 67 67 65 72 20 70 72  hat a trigger pr
2510: 6f 67 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20 62  ogram will not b
2520: 65 20 61 62 6c 65 20 74 6f 20 69 74 73 65 6c 66  e able to itself
2530: 0a 2a 2a 20 66 69 72 65 20 61 6e 79 20 74 72 69  .** fire any tri
2540: 67 67 65 72 73 2e 20 41 20 76 61 6c 75 65 20 6f  ggers. A value o
2550: 66 20 30 20 6d 65 61 6e 73 20 74 68 61 74 20 6e  f 0 means that n
2560: 6f 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  o trigger progra
2570: 6d 73 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d 61  ms at all .** ma
2580: 79 20 62 65 20 65 78 65 63 75 74 65 64 2e 0a 2a  y be executed..*
2590: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
25a0: 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50  _MAX_TRIGGER_DEP
25b0: 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  TH.# define SQLI
25c0: 54 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44  TE_MAX_TRIGGER_D
25d0: 45 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66  EPTH 1000.#endif
25e0: 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ../*************
25f0: 2a 20 45 6e 64 20 6f 66 20 73 71 6c 69 74 65 4c  * End of sqliteL
2600: 69 6d 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  imit.h *********
2610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2630: 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
2640: 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65  * Continuing whe
2650: 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69  re we left off i
2660: 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a  n sqliteInt.h **
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2680: 2f 0a 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e 75  /../* Disable nu
2690: 69 73 61 6e 63 65 20 77 61 72 6e 69 6e 67 73 20  isance warnings 
26a0: 6f 6e 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70 69  on Borland compi
26b0: 6c 65 72 73 20 2a 2f 0a 23 69 66 20 64 65 66 69  lers */.#if defi
26c0: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
26d0: 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d  ).#pragma warn -
26e0: 72 63 68 20 2f 2a 20 75 6e 72 65 61 63 68 61 62  rch /* unreachab
26f0: 6c 65 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61 67  le code */.#prag
2700: 6d 61 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a 20  ma warn -ccc /* 
2710: 43 6f 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c 77  Condition is alw
2720: 61 79 73 20 74 72 75 65 20 6f 72 20 66 61 6c 73  ays true or fals
2730: 65 20 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61 72  e */.#pragma war
2740: 6e 20 2d 61 75 73 20 2f 2a 20 41 73 73 69 67 6e  n -aus /* Assign
2750: 65 64 20 76 61 6c 75 65 20 69 73 20 6e 65 76 65  ed value is neve
2760: 72 20 75 73 65 64 20 2a 2f 0a 23 70 72 61 67 6d  r used */.#pragm
2770: 61 20 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20 43  a warn -csu /* C
2780: 6f 6d 70 61 72 69 6e 67 20 73 69 67 6e 65 64 20  omparing signed 
2790: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f 0a  and unsigned */.
27a0: 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 73 70  #pragma warn -sp
27b0: 61 20 2f 2a 20 53 75 73 70 69 63 69 6f 75 73 20  a /* Suspicious 
27c0: 70 6f 69 6e 74 65 72 20 61 72 69 74 68 6d 65 74  pointer arithmet
27d0: 69 63 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a  ic */.#endif../*
27e0: 20 4e 65 65 64 65 64 20 66 6f 72 20 76 61 72 69   Needed for vari
27f0: 6f 75 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e  ous definitions.
2800: 2e 2e 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 47  .. */.#ifndef _G
2810: 4e 55 5f 53 4f 55 52 43 45 0a 23 20 64 65 66 69  NU_SOURCE.# defi
2820: 6e 65 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23  ne _GNU_SOURCE.#
2830: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63  endif../*.** Inc
2840: 6c 75 64 65 20 73 74 61 6e 64 61 72 64 20 68 65  lude standard he
2850: 61 64 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65  ader files as ne
2860: 63 65 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65  cessary.*/.#ifde
2870: 66 20 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a  f HAVE_STDINT_H.
2880: 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74  #include <stdint
2890: 2e 68 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  .h>.#endif.#ifde
28a0: 66 20 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f  f HAVE_INTTYPES_
28b0: 48 0a 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74  H.#include <intt
28c0: 79 70 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a  ypes.h>.#endif..
28d0: 2f 2a 0a 2a 2a 20 54 68 65 20 6e 75 6d 62 65 72  /*.** The number
28e0: 20 6f 66 20 73 61 6d 70 6c 65 73 20 6f 66 20 61   of samples of a
28f0: 6e 20 69 6e 64 65 78 20 74 68 61 74 20 53 51 4c  n index that SQL
2900: 69 74 65 20 74 61 6b 65 73 20 69 6e 20 6f 72 64  ite takes in ord
2910: 65 72 20 74 6f 20 0a 2a 2a 20 63 6f 6e 73 74 72  er to .** constr
2920: 75 63 74 20 61 20 68 69 73 74 6f 67 72 61 6d 20  uct a histogram 
2930: 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e  of the table con
2940: 74 65 6e 74 20 77 68 65 6e 20 72 75 6e 6e 69 6e  tent when runnin
2950: 67 20 41 4e 41 4c 59 5a 45 0a 2a 2a 20 61 6e 64  g ANALYZE.** and
2960: 20 77 69 74 68 20 53 51 4c 49 54 45 5f 45 4e 41   with SQLITE_ENA
2970: 42 4c 45 5f 53 54 41 54 32 0a 2a 2f 0a 23 64 65  BLE_STAT2.*/.#de
2980: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
2990: 58 5f 53 41 4d 50 4c 45 53 20 31 30 0a 0a 2f 2a  X_SAMPLES 10../*
29a0: 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
29b0: 67 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65  g macros are use
29c0: 64 20 74 6f 20 63 61 73 74 20 70 6f 69 6e 74 65  d to cast pointe
29d0: 72 73 20 74 6f 20 69 6e 74 65 67 65 72 73 20 61  rs to integers a
29e0: 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 74  nd.** integers t
29f0: 6f 20 70 6f 69 6e 74 65 72 73 2e 20 20 54 68 65  o pointers.  The
2a00: 20 77 61 79 20 79 6f 75 20 64 6f 20 74 68 69 73   way you do this
2a10: 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65   varies from one
2a20: 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20   compiler.** to 
2a30: 74 68 65 20 6e 65 78 74 2c 20 73 6f 20 77 65 20  the next, so we 
2a40: 68 61 76 65 20 64 65 76 65 6c 6f 70 65 64 20 74  have developed t
2a50: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65 74  he following set
2a60: 20 6f 66 20 23 69 66 20 73 74 61 74 65 6d 65 6e   of #if statemen
2a70: 74 73 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61 74  ts.** to generat
2a80: 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 6d 61  e appropriate ma
2a90: 63 72 6f 73 20 66 6f 72 20 61 20 77 69 64 65 20  cros for a wide 
2aa0: 72 61 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c 65  range of compile
2ab0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  rs..**.** The co
2ac0: 72 72 65 63 74 20 22 41 4e 53 49 22 20 77 61 79  rrect "ANSI" way
2ad0: 20 74 6f 20 64 6f 20 74 68 69 73 20 69 73 20 74   to do this is t
2ae0: 6f 20 75 73 65 20 74 68 65 20 69 6e 74 70 74 72  o use the intptr
2af0: 5f 74 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e 66  _t type. .** Unf
2b00: 6f 72 74 75 6e 61 74 65 6c 79 2c 20 74 68 61 74  ortunately, that
2b10: 20 74 79 70 65 64 65 66 20 69 73 20 6e 6f 74 20   typedef is not 
2b20: 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c 6c  available on all
2b30: 20 63 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a 2a   compilers, or.*
2b40: 2a 20 69 66 20 69 74 20 69 73 20 61 76 61 69 6c  * if it is avail
2b50: 61 62 6c 65 2c 20 69 74 20 72 65 71 75 69 72 65  able, it require
2b60: 73 20 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f 66  s an #include of
2b70: 20 73 70 65 63 69 66 69 63 20 68 65 61 64 65 72   specific header
2b80: 73 0a 2a 2a 20 74 68 61 74 20 76 61 72 79 20 66  s.** that vary f
2b90: 72 6f 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65 20  rom one machine 
2ba0: 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a  to the next..**.
2bb0: 2a 2a 20 54 69 63 6b 65 74 20 23 33 38 36 30 3a  ** Ticket #3860:
2bc0: 20 20 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d 34    The llvm-gcc-4
2bd0: 2e 32 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f 6d  .2 compiler from
2be0: 20 41 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f 6e   Apple chokes on
2bf0: 0a 2a 2a 20 74 68 65 20 28 28 76 6f 69 64 2a 29  .** the ((void*)
2c00: 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 20  &((char*)0)[X]) 
2c10: 63 6f 6e 73 74 72 75 63 74 2e 20 20 42 75 74 20  construct.  But 
2c20: 4d 53 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20 28  MSVC chokes on (
2c30: 28 76 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a 20  (void*)(X))..** 
2c40: 53 6f 20 77 65 20 68 61 76 65 20 74 6f 20 64 65  So we have to de
2c50: 66 69 6e 65 20 74 68 65 20 6d 61 63 72 6f 73 20  fine the macros 
2c60: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 77 61 79  in different way
2c70: 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  s depending on t
2c80: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e 0a  he.** compiler..
2c90: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f  */.#if defined(_
2ca0: 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29  _PTRDIFF_TYPE__)
2cb0: 20 20 2f 2a 20 54 68 69 73 20 63 61 73 65 20 73    /* This case s
2cc0: 68 6f 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20 47  hould work for G
2cd0: 43 43 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 53  CC */.# define S
2ce0: 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 52  QLITE_INT_TO_PTR
2cf0: 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 5f 5f  (X)  ((void*)(__
2d00: 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 28  PTRDIFF_TYPE__)(
2d10: 58 29 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  X)).# define SQL
2d20: 49 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58  ITE_PTR_TO_INT(X
2d30: 29 20 20 28 28 69 6e 74 29 28 5f 5f 50 54 52 44  )  ((int)(__PTRD
2d40: 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29 29 0a  IFF_TYPE__)(X)).
2d50: 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28 5f  #elif !defined(_
2d60: 5f 47 4e 55 43 5f 5f 29 20 20 20 20 20 20 20 2f  _GNUC__)       /
2d70: 2a 20 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d 70  * Works for comp
2d80: 69 6c 65 72 73 20 6f 74 68 65 72 20 74 68 61 6e  ilers other than
2d90: 20 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69 6e   LLVM */.# defin
2da0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f  e SQLITE_INT_TO_
2db0: 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29  PTR(X)  ((void*)
2dc0: 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 0a  &((char*)0)[X]).
2dd0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2de0: 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28  PTR_TO_INT(X)  (
2df0: 28 69 6e 74 29 28 28 28 63 68 61 72 2a 29 58 29  (int)(((char*)X)
2e00: 2d 28 63 68 61 72 2a 29 30 29 29 0a 23 65 6c 69  -(char*)0)).#eli
2e10: 66 20 64 65 66 69 6e 65 64 28 48 41 56 45 5f 53  f defined(HAVE_S
2e20: 54 44 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55 73  TDINT_H)   /* Us
2e30: 65 20 74 68 69 73 20 63 61 73 65 20 69 66 20 77  e this case if w
2e40: 65 20 68 61 76 65 20 41 4e 53 49 20 68 65 61 64  e have ANSI head
2e50: 65 72 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20  ers */.# define 
2e60: 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54  SQLITE_INT_TO_PT
2e70: 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 69  R(X)  ((void*)(i
2e80: 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23 20 64  ntptr_t)(X)).# d
2e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52  efine SQLITE_PTR
2ea0: 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e  _TO_INT(X)  ((in
2eb0: 74 29 28 69 6e 74 70 74 72 5f 74 29 28 58 29 29  t)(intptr_t)(X))
2ec0: 0a 23 65 6c 73 65 20 20 20 20 20 20 20 20 20 20  .#else          
2ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ee0: 2f 2a 20 47 65 6e 65 72 61 74 65 73 20 61 20 77  /* Generates a w
2ef0: 61 72 6e 69 6e 67 20 2d 20 62 75 74 20 69 74 20  arning - but it 
2f00: 61 6c 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f 0a  always works */.
2f10: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2f20: 49 4e 54 5f 54 4f 5f 50 54 52 28 58 29 20 20 28  INT_TO_PTR(X)  (
2f30: 28 76 6f 69 64 2a 29 28 58 29 29 0a 23 20 64 65  (void*)(X)).# de
2f40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 5f  fine SQLITE_PTR_
2f50: 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e 74  TO_INT(X)  ((int
2f60: 29 28 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a  )(X)).#endif../*
2f70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 54  .** The SQLITE_T
2f80: 48 52 45 41 44 53 41 46 45 20 6d 61 63 72 6f 20  HREADSAFE macro 
2f90: 6d 75 73 74 20 62 65 20 64 65 66 69 6e 65 64 20  must be defined 
2fa0: 61 73 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a 2a  as 0, 1, or 2..*
2fb0: 2a 20 30 20 6d 65 61 6e 73 20 6d 75 74 65 78 65  * 0 means mutexe
2fc0: 73 20 61 72 65 20 70 65 72 6d 61 6e 65 6e 74 6c  s are permanentl
2fd0: 79 20 64 69 73 61 62 6c 65 20 61 6e 64 20 74 68  y disable and th
2fe0: 65 20 6c 69 62 72 61 72 79 20 69 73 20 6e 65 76  e library is nev
2ff0: 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 61 66 65  er.** threadsafe
3000: 2e 20 20 31 20 6d 65 61 6e 73 20 74 68 65 20 6c  .  1 means the l
3010: 69 62 72 61 72 79 20 69 73 20 73 65 72 69 61 6c  ibrary is serial
3020: 69 7a 65 64 20 77 68 69 63 68 20 69 73 20 74 68  ized which is th
3030: 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65 76  e highest.** lev
3040: 65 6c 20 6f 66 20 74 68 72 65 61 64 73 61 66 65  el of threadsafe
3050: 74 79 2e 20 20 32 20 6d 65 61 6e 73 20 74 68 65  ty.  2 means the
3060: 20 6c 69 62 61 72 79 20 69 73 20 6d 75 6c 74 69   libary is multi
3070: 74 68 72 65 61 64 65 64 20 2d 20 6d 75 6c 74 69  threaded - multi
3080: 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64 73 20 63  ple.** threads c
3090: 61 6e 20 75 73 65 20 53 51 4c 69 74 65 20 61 73  an use SQLite as
30a0: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
30b0: 74 68 72 65 61 64 73 20 74 72 79 20 74 6f 20 75  threads try to u
30c0: 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  se the same.** d
30d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30e0: 6f 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  on at the same t
30f0: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65 72  ime..**.** Older
3100: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
3110: 69 74 65 20 75 73 65 64 20 61 6e 20 6f 70 74 69  ite used an opti
3120: 6f 6e 61 6c 20 54 48 52 45 41 44 53 41 46 45 20  onal THREADSAFE 
3130: 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75 70  macro..** We sup
3140: 70 6f 72 74 20 74 68 61 74 20 66 6f 72 20 6c 65  port that for le
3150: 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64 65  gacy..*/.#if !de
3160: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 48 52  fined(SQLITE_THR
3170: 45 41 44 53 41 46 45 29 0a 23 69 66 20 64 65 66  EADSAFE).#if def
3180: 69 6e 65 64 28 54 48 52 45 41 44 53 41 46 45 29  ined(THREADSAFE)
3190: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
31a0: 5f 54 48 52 45 41 44 53 41 46 45 20 54 48 52 45  _THREADSAFE THRE
31b0: 41 44 53 41 46 45 0a 23 65 6c 73 65 0a 23 20 64  ADSAFE.#else.# d
31c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 48 52  efine SQLITE_THR
31d0: 45 41 44 53 41 46 45 20 31 20 2f 2a 20 49 4d 50  EADSAFE 1 /* IMP
31e0: 3a 20 52 2d 30 37 32 37 32 2d 32 32 33 30 39 20  : R-07272-22309 
31f0: 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66  */.#endif.#endif
3200: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ../*.** The SQLI
3210: 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
3220: 41 54 55 53 20 6d 61 63 72 6f 20 6d 75 73 74 20  ATUS macro must 
3230: 62 65 20 64 65 66 69 6e 65 64 20 61 73 20 65 69  be defined as ei
3240: 74 68 65 72 20 30 20 6f 72 20 31 2e 0a 2a 2a 20  ther 0 or 1..** 
3250: 49 74 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  It determines wh
3260: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
3270: 20 66 65 61 74 75 72 65 73 20 72 65 6c 61 74 65   features relate
3280: 64 20 74 6f 20 0a 2a 2a 20 53 51 4c 49 54 45 5f  d to .** SQLITE_
3290: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
32a0: 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 62   are available b
32b0: 79 20 64 65 66 61 75 6c 74 20 6f 72 20 6e 6f 74  y default or not
32c0: 2e 20 54 68 69 73 20 76 61 6c 75 65 20 63 61 6e  . This value can
32d0: 0a 2a 2a 20 62 65 20 6f 76 65 72 72 69 64 64 65  .** be overridde
32e0: 6e 20 61 74 20 72 75 6e 74 69 6d 65 20 75 73 69  n at runtime usi
32f0: 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
3300: 6f 6e 66 69 67 28 29 20 41 50 49 2e 0a 2a 2f 0a  onfig() API..*/.
3310: 23 69 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c  #if !defined(SQL
3320: 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
3330: 54 41 54 55 53 29 0a 23 20 64 65 66 69 6e 65 20  TATUS).# define 
3340: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
3350: 45 4d 53 54 41 54 55 53 20 31 0a 23 65 6e 64 69  EMSTATUS 1.#endi
3360: 66 0a 0a 2f 2a 0a 2a 2a 20 45 78 61 63 74 6c 79  f../*.** Exactly
3370: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
3380: 6f 77 69 6e 67 20 6d 61 63 72 6f 73 20 6d 75 73  owing macros mus
3390: 74 20 62 65 20 64 65 66 69 6e 65 64 20 69 6e 20  t be defined in 
33a0: 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 73 70 65 63  order to.** spec
33b0: 69 66 79 20 77 68 69 63 68 20 6d 65 6d 6f 72 79  ify which memory
33c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
33d0: 79 73 74 65 6d 20 74 6f 20 75 73 65 2e 0a 2a 2a  ystem to use..**
33e0: 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 53  .**     SQLITE_S
33f0: 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 20 20 20  YSTEM_MALLOC    
3400: 20 20 20 20 20 20 2f 2f 20 55 73 65 20 6e 6f 72        // Use nor
3410: 6d 61 6c 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  mal system mallo
3420: 63 28 29 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  c().**     SQLIT
3430: 45 5f 4d 45 4d 44 45 42 55 47 20 20 20 20 20 20  E_MEMDEBUG      
3440: 20 20 20 20 20 20 20 20 20 2f 2f 20 44 65 62 75           // Debu
3450: 67 67 69 6e 67 20 76 65 72 73 69 6f 6e 20 6f 66  gging version of
3460: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
3470: 0a 2a 2a 0a 2a 2a 20 28 48 69 73 74 6f 72 69 63  .**.** (Historic
3480: 61 6c 20 6e 6f 74 65 3a 20 20 54 68 65 72 65 20  al note:  There 
3490: 75 73 65 64 20 74 6f 20 62 65 20 73 65 76 65 72  used to be sever
34a0: 61 6c 20 6f 74 68 65 72 20 6f 70 74 69 6f 6e 73  al other options
34b0: 2c 20 62 75 74 20 77 65 27 76 65 0a 2a 2a 20 70  , but we've.** p
34c0: 61 72 65 64 20 69 74 20 64 6f 77 6e 20 74 6f 20  ared it down to 
34d0: 6a 75 73 74 20 74 68 65 73 65 20 74 77 6f 2e 29  just these two.)
34e0: 0a 2a 2a 0a 2a 2a 20 49 66 20 6e 6f 6e 65 20 6f  .**.** If none o
34f0: 66 20 74 68 65 20 61 62 6f 76 65 20 61 72 65 20  f the above are 
3500: 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 73 65  defined, then se
3510: 74 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f  t SQLITE_SYSTEM_
3520: 4d 41 4c 4c 4f 43 20 61 73 0a 2a 2a 20 74 68 65  MALLOC as.** the
3530: 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 23 69 66   default..*/.#if
3540: 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f   defined(SQLITE_
3550: 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 29 2b 64  SYSTEM_MALLOC)+d
3560: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d 45  efined(SQLITE_ME
3570: 4d 44 45 42 55 47 29 3e 31 0a 23 20 65 72 72 6f  MDEBUG)>1.# erro
3580: 72 20 22 41 74 20 6d 6f 73 74 20 6f 6e 65 20 6f  r "At most one o
3590: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
35a0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e  compile-time con
35b0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
35c0: 6e 73 5c 0a 20 69 73 20 61 6c 6c 6f 77 73 3a 20  ns\. is allows: 
35d0: 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41  SQLITE_SYSTEM_MA
35e0: 4c 4c 4f 43 2c 20 53 51 4c 49 54 45 5f 4d 45 4d  LLOC, SQLITE_MEM
35f0: 44 45 42 55 47 22 0a 23 65 6e 64 69 66 0a 23 69  DEBUG".#endif.#i
3600: 66 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45  f defined(SQLITE
3610: 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 29 2b  _SYSTEM_MALLOC)+
3620: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d  defined(SQLITE_M
3630: 45 4d 44 45 42 55 47 29 3d 3d 30 0a 23 20 64 65  EMDEBUG)==0.# de
3640: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 53 54  fine SQLITE_SYST
3650: 45 4d 5f 4d 41 4c 4c 4f 43 20 31 0a 23 65 6e 64  EM_MALLOC 1.#end
3660: 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 53 51 4c  if../*.** If SQL
3670: 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f  ITE_MALLOC_SOFT_
3680: 4c 49 4d 49 54 20 69 73 20 6e 6f 74 20 7a 65 72  LIMIT is not zer
3690: 6f 2c 20 74 68 65 6e 20 74 72 79 20 74 6f 20 6b  o, then try to k
36a0: 65 65 70 20 74 68 65 0a 2a 2a 20 73 69 7a 65 73  eep the.** sizes
36b0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
36c0: 61 74 69 6f 6e 73 20 62 65 6c 6f 77 20 74 68 69  ations below thi
36d0: 73 20 76 61 6c 75 65 20 77 68 65 72 65 20 70 6f  s value where po
36e0: 73 73 69 62 6c 65 2e 0a 2a 2f 0a 23 69 66 20 21  ssible..*/.#if !
36f0: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d  defined(SQLITE_M
3700: 41 4c 4c 4f 43 5f 53 4f 46 54 5f 4c 49 4d 49 54  ALLOC_SOFT_LIMIT
3710: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  ).# define SQLIT
3720: 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f 4c 49  E_MALLOC_SOFT_LI
3730: 4d 49 54 20 31 30 32 34 0a 23 65 6e 64 69 66 0a  MIT 1024.#endif.
3740: 0a 2f 2a 0a 2a 2a 20 57 65 20 6e 65 65 64 20 74  ./*.** We need t
3750: 6f 20 64 65 66 69 6e 65 20 5f 58 4f 50 45 4e 5f  o define _XOPEN_
3760: 53 4f 55 52 43 45 20 61 73 20 66 6f 6c 6c 6f 77  SOURCE as follow
3770: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  s in order to en
3780: 61 62 6c 65 0a 2a 2a 20 72 65 63 75 72 73 69 76  able.** recursiv
3790: 65 20 6d 75 74 65 78 65 73 20 6f 6e 20 6d 6f 73  e mutexes on mos
37a0: 74 20 55 6e 69 78 20 73 79 73 74 65 6d 73 2e 20  t Unix systems. 
37b0: 20 42 75 74 20 4d 61 63 20 4f 53 20 58 20 69 73   But Mac OS X is
37c0: 20 64 69 66 66 65 72 65 6e 74 2e 0a 2a 2a 20 54   different..** T
37d0: 68 65 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45  he _XOPEN_SOURCE
37e0: 20 64 65 66 69 6e 65 20 63 61 75 73 65 73 20 70   define causes p
37f0: 72 6f 62 6c 65 6d 73 20 66 6f 72 20 4d 61 63 20  roblems for Mac 
3800: 4f 53 20 58 20 77 65 20 61 72 65 20 74 6f 6c 64  OS X we are told
3810: 2c 0a 2a 2a 20 73 6f 20 69 74 20 69 73 20 6f 6d  ,.** so it is om
3820: 69 74 74 65 64 20 74 68 65 72 65 2e 20 20 53 65  itted there.  Se
3830: 65 20 74 69 63 6b 65 74 20 23 32 36 37 33 2e 0a  e ticket #2673..
3840: 2a 2a 0a 2a 2a 20 4c 61 74 65 72 20 77 65 20 6c  **.** Later we l
3850: 65 61 72 6e 20 74 68 61 74 20 5f 58 4f 50 45 4e  earn that _XOPEN
3860: 5f 53 4f 55 52 43 45 20 69 73 20 70 6f 6f 72 6c  _SOURCE is poorl
3870: 79 20 6f 72 20 69 6e 63 6f 72 72 65 63 74 6c 79  y or incorrectly
3880: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  .** implemented 
3890: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
38a0: 20 20 53 6f 20 77 65 20 61 76 6f 69 64 20 64 65    So we avoid de
38b0: 66 69 6e 69 6e 67 20 69 74 20 61 74 20 61 6c 6c  fining it at all
38c0: 0a 2a 2a 20 69 66 20 69 74 20 69 73 20 61 6c 72  .** if it is alr
38d0: 65 61 64 79 20 64 65 66 69 6e 65 64 20 6f 72 20  eady defined or 
38e0: 69 66 20 69 74 20 69 73 20 75 6e 6e 65 65 64 65  if it is unneede
38f0: 64 20 62 65 63 61 75 73 65 20 77 65 20 61 72 65  d because we are
3900: 0a 2a 2a 20 6e 6f 74 20 64 6f 69 6e 67 20 61 20  .** not doing a 
3910: 74 68 72 65 61 64 73 61 66 65 20 62 75 69 6c 64  threadsafe build
3920: 2e 20 20 54 69 63 6b 65 74 20 23 32 36 38 31 2e  .  Ticket #2681.
3930: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
3940: 74 69 63 6b 65 74 20 23 32 37 34 31 2e 0a 2a 2f  ticket #2741..*/
3950: 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28 5f 58  .#if !defined(_X
3960: 4f 50 45 4e 5f 53 4f 55 52 43 45 29 20 26 26 20  OPEN_SOURCE) && 
3970: 21 64 65 66 69 6e 65 64 28 5f 5f 44 41 52 57 49  !defined(__DARWI
3980: 4e 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64  N__) && !defined
3990: 28 5f 5f 41 50 50 4c 45 5f 5f 29 20 26 26 20 53  (__APPLE__) && S
39a0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
39b0: 0a 23 20 20 64 65 66 69 6e 65 20 5f 58 4f 50 45  .#  define _XOPE
39c0: 4e 5f 53 4f 55 52 43 45 20 35 30 30 20 20 2f 2a  N_SOURCE 500  /*
39d0: 20 4e 65 65 64 65 64 20 74 6f 20 65 6e 61 62 6c   Needed to enabl
39e0: 65 20 70 74 68 72 65 61 64 20 72 65 63 75 72 73  e pthread recurs
39f0: 69 76 65 20 6d 75 74 65 78 65 73 20 2a 2f 0a 23  ive mutexes */.#
3a00: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  endif../*.** The
3a10: 20 54 43 4c 20 68 65 61 64 65 72 73 20 61 72 65   TCL headers are
3a20: 20 6f 6e 6c 79 20 6e 65 65 64 65 64 20 77 68 65   only needed whe
3a30: 6e 20 63 6f 6d 70 69 6c 69 6e 67 20 74 68 65 20  n compiling the 
3a40: 54 43 4c 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2f  TCL bindings..*/
3a50: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53 51 4c  .#if defined(SQL
3a60: 49 54 45 5f 54 43 4c 29 20 7c 7c 20 64 65 66 69  ITE_TCL) || defi
3a70: 6e 65 64 28 54 43 4c 53 48 29 0a 23 20 69 6e 63  ned(TCLSH).# inc
3a80: 6c 75 64 65 20 3c 74 63 6c 2e 68 3e 0a 23 65 6e  lude <tcl.h>.#en
3a90: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6e 79 20  dif../*.** Many 
3aa0: 70 65 6f 70 6c 65 20 61 72 65 20 66 61 69 6c 69  people are faili
3ab0: 6e 67 20 74 6f 20 73 65 74 20 2d 44 4e 44 45 42  ng to set -DNDEB
3ac0: 55 47 3d 31 20 77 68 65 6e 20 63 6f 6d 70 69 6c  UG=1 when compil
3ad0: 69 6e 67 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 53  ing SQLite..** S
3ae0: 65 74 74 69 6e 67 20 4e 44 45 42 55 47 20 6d 61  etting NDEBUG ma
3af0: 6b 65 73 20 74 68 65 20 63 6f 64 65 20 73 6d 61  kes the code sma
3b00: 6c 6c 65 72 20 61 6e 64 20 72 75 6e 20 66 61 73  ller and run fas
3b10: 74 65 72 2e 20 20 53 6f 20 74 68 65 20 66 6f 6c  ter.  So the fol
3b20: 6c 6f 77 69 6e 67 0a 2a 2a 20 6c 69 6e 65 73 20  lowing.** lines 
3b30: 61 72 65 20 61 64 64 65 64 20 74 6f 20 61 75 74  are added to aut
3b40: 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 74 20 4e  omatically set N
3b50: 44 45 42 55 47 20 75 6e 6c 65 73 73 20 74 68 65  DEBUG unless the
3b60: 20 2d 44 53 51 4c 49 54 45 5f 44 45 42 55 47 3d   -DSQLITE_DEBUG=
3b70: 31 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 73  1.** option is s
3b80: 65 74 2e 20 20 54 68 75 73 20 4e 44 45 42 55 47  et.  Thus NDEBUG
3b90: 20 62 65 63 6f 6d 65 73 20 61 6e 20 6f 70 74 2d   becomes an opt-
3ba0: 69 6e 20 72 61 74 68 65 72 20 74 68 61 6e 20 61  in rather than a
3bb0: 6e 20 6f 70 74 2d 6f 75 74 0a 2a 2a 20 66 65 61  n opt-out.** fea
3bc0: 74 75 72 65 2e 0a 2a 2f 0a 23 69 66 20 21 64 65  ture..*/.#if !de
3bd0: 66 69 6e 65 64 28 4e 44 45 42 55 47 29 20 26 26  fined(NDEBUG) &&
3be0: 20 21 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45   !defined(SQLITE
3bf0: 5f 44 45 42 55 47 29 20 0a 23 20 64 65 66 69 6e  _DEBUG) .# defin
3c00: 65 20 4e 44 45 42 55 47 20 31 0a 23 65 6e 64 69  e NDEBUG 1.#endi
3c10: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 65 73  f../*.** The tes
3c20: 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20 69 73  tcase() macro is
3c30: 20 75 73 65 64 20 74 6f 20 61 69 64 20 69 6e 20   used to aid in 
3c40: 63 6f 76 65 72 61 67 65 20 74 65 73 74 69 6e 67  coverage testing
3c50: 2e 20 20 57 68 65 6e 20 0a 2a 2a 20 64 6f 69 6e  .  When .** doin
3c60: 67 20 63 6f 76 65 72 61 67 65 20 74 65 73 74 69  g coverage testi
3c70: 6e 67 2c 20 74 68 65 20 63 6f 6e 64 69 74 69 6f  ng, the conditio
3c80: 6e 20 69 6e 73 69 64 65 20 74 68 65 20 61 72 67  n inside the arg
3c90: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 65 73 74  ument to.** test
3ca0: 63 61 73 65 28 29 20 6d 75 73 74 20 62 65 20 65  case() must be e
3cb0: 76 61 6c 75 61 74 65 64 20 62 6f 74 68 20 74 72  valuated both tr
3cc0: 75 65 20 61 6e 64 20 66 61 6c 73 65 20 69 6e 20  ue and false in 
3cd0: 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 67 65 74 20  order to.** get 
3ce0: 66 75 6c 6c 20 62 72 61 6e 63 68 20 63 6f 76 65  full branch cove
3cf0: 72 61 67 65 2e 20 20 54 68 65 20 74 65 73 74 63  rage.  The testc
3d00: 61 73 65 28 29 20 6d 61 63 72 6f 20 69 73 20 69  ase() macro is i
3d10: 6e 73 65 72 74 65 64 0a 2a 2a 20 74 6f 20 68 65  nserted.** to he
3d20: 6c 70 20 65 6e 73 75 72 65 20 61 64 65 71 75 61  lp ensure adequa
3d30: 74 65 20 74 65 73 74 20 63 6f 76 65 72 61 67 65  te test coverage
3d40: 20 69 6e 20 70 6c 61 63 65 73 20 77 68 65 72 65   in places where
3d50: 20 73 69 6d 70 6c 65 0a 2a 2a 20 63 6f 6e 64 69   simple.** condi
3d60: 74 69 6f 6e 2f 64 65 63 69 73 69 6f 6e 20 63 6f  tion/decision co
3d70: 76 65 72 61 67 65 20 69 73 20 69 6e 61 64 65 71  verage is inadeq
3d80: 75 61 74 65 2e 20 20 46 6f 72 20 65 78 61 6d 70  uate.  For examp
3d90: 6c 65 2c 20 74 65 73 74 63 61 73 65 28 29 0a 2a  le, testcase().*
3da0: 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
3db0: 20 6d 61 6b 65 20 73 75 72 65 20 62 6f 75 6e 64   make sure bound
3dc0: 61 72 79 20 76 61 6c 75 65 73 20 61 72 65 20 74  ary values are t
3dd0: 65 73 74 65 64 2e 20 20 46 6f 72 0a 2a 2a 20 62  ested.  For.** b
3de0: 69 74 6d 61 73 6b 20 74 65 73 74 73 2c 20 74 65  itmask tests, te
3df0: 73 74 63 61 73 65 28 29 20 63 61 6e 20 62 65 20  stcase() can be 
3e00: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 73 75 72  used to make sur
3e10: 65 20 65 61 63 68 20 62 69 74 0a 2a 2a 20 69 73  e each bit.** is
3e20: 20 73 69 67 6e 69 66 69 63 61 6e 74 20 61 6e 64   significant and
3e30: 20 75 73 65 64 20 61 74 20 6c 65 61 73 74 20 6f   used at least o
3e40: 6e 63 65 2e 20 20 4f 6e 20 73 77 69 74 63 68 20  nce.  On switch 
3e50: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 77 68  statements.** wh
3e60: 65 72 65 20 6d 75 6c 74 69 70 6c 65 20 63 61 73  ere multiple cas
3e70: 65 73 20 67 6f 20 74 6f 20 74 68 65 20 73 61 6d  es go to the sam
3e80: 65 20 62 6c 6f 63 6b 20 6f 66 20 63 6f 64 65 2c  e block of code,
3e90: 20 74 65 73 74 63 61 73 65 28 29 0a 2a 2a 20 63   testcase().** c
3ea0: 61 6e 20 69 6e 73 75 72 65 20 74 68 61 74 20 61  an insure that a
3eb0: 6c 6c 20 63 61 73 65 73 20 61 72 65 20 65 76 61  ll cases are eva
3ec0: 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2f 0a 23 69  luated..**.*/.#i
3ed0: 66 64 65 66 20 53 51 4c 49 54 45 5f 43 4f 56 45  fdef SQLITE_COVE
3ee0: 52 41 47 45 5f 54 45 53 54 0a 53 51 4c 49 54 45  RAGE_TEST.SQLITE
3ef0: 5f 50 52 49 56 41 54 45 20 20 20 76 6f 69 64 20  _PRIVATE   void 
3f00: 73 71 6c 69 74 65 33 43 6f 76 65 72 61 67 65 28  sqlite3Coverage(
3f10: 69 6e 74 29 3b 0a 23 20 64 65 66 69 6e 65 20 74  int);.# define t
3f20: 65 73 74 63 61 73 65 28 58 29 20 20 69 66 28 20  estcase(X)  if( 
3f30: 58 20 29 7b 20 73 71 6c 69 74 65 33 43 6f 76 65  X ){ sqlite3Cove
3f40: 72 61 67 65 28 5f 5f 4c 49 4e 45 5f 5f 29 3b 20  rage(__LINE__); 
3f50: 7d 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  }.#else.# define
3f60: 20 74 65 73 74 63 61 73 65 28 58 29 0a 23 65 6e   testcase(X).#en
3f70: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 54  dif../*.** The T
3f80: 45 53 54 4f 4e 4c 59 20 6d 61 63 72 6f 20 69 73  ESTONLY macro is
3f90: 20 75 73 65 64 20 74 6f 20 65 6e 63 6c 6f 73 65   used to enclose
3fa0: 20 76 61 72 69 61 62 6c 65 20 64 65 63 6c 61 72   variable declar
3fb0: 61 74 69 6f 6e 73 20 6f 72 0a 2a 2a 20 6f 74 68  ations or.** oth
3fc0: 65 72 20 62 69 74 73 20 6f 66 20 63 6f 64 65 20  er bits of code 
3fd0: 74 68 61 74 20 61 72 65 20 6e 65 65 64 65 64 20  that are needed 
3fe0: 74 6f 20 73 75 70 70 6f 72 74 20 74 68 65 20 61  to support the a
3ff0: 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 77 69 74 68  rguments.** with
4000: 69 6e 20 74 65 73 74 63 61 73 65 28 29 20 61 6e  in testcase() an
4010: 64 20 61 73 73 65 72 74 28 29 20 6d 61 63 72 6f  d assert() macro
4020: 73 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e  s..*/.#if !defin
4030: 65 64 28 4e 44 45 42 55 47 29 20 7c 7c 20 64 65  ed(NDEBUG) || de
4040: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 43 4f 56  fined(SQLITE_COV
4050: 45 52 41 47 45 5f 54 45 53 54 29 0a 23 20 64 65  ERAGE_TEST).# de
4060: 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28 58 29  fine TESTONLY(X)
4070: 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65 66 69    X.#else.# defi
4080: 6e 65 20 54 45 53 54 4f 4e 4c 59 28 58 29 0a 23  ne TESTONLY(X).#
4090: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 53 6f 6d  endif../*.** Som
40a0: 65 74 69 6d 65 73 20 77 65 20 6e 65 65 64 20 61  etimes we need a
40b0: 20 73 6d 61 6c 6c 20 61 6d 6f 75 6e 74 20 6f 66   small amount of
40c0: 20 63 6f 64 65 20 73 75 63 68 20 61 73 20 61 20   code such as a 
40d0: 76 61 72 69 61 62 6c 65 20 69 6e 69 74 69 61 6c  variable initial
40e0: 69 7a 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 73 65  ization.** to se
40f0: 74 75 70 20 66 6f 72 20 61 20 6c 61 74 65 72 20  tup for a later 
4100: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
4110: 6e 74 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 77  nt.  We do not w
4120: 61 6e 74 20 74 68 69 73 20 63 6f 64 65 20 74 6f  ant this code to
4130: 0a 2a 2a 20 61 70 70 65 61 72 20 77 68 65 6e 20  .** appear when 
4140: 61 73 73 65 72 74 28 29 20 69 73 20 64 69 73 61  assert() is disa
4150: 62 6c 65 64 2e 20 20 54 68 65 20 66 6f 6c 6c 6f  bled.  The follo
4160: 77 69 6e 67 20 6d 61 63 72 6f 20 69 73 20 74 68  wing macro is th
4170: 65 72 65 66 6f 72 65 0a 2a 2a 20 75 73 65 64 20  erefore.** used 
4180: 74 6f 20 63 6f 6e 74 61 69 6e 20 74 68 61 74 20  to contain that 
4190: 73 65 74 75 70 20 63 6f 64 65 2e 20 20 54 68 65  setup code.  The
41a0: 20 22 56 56 41 22 20 61 63 72 6f 6e 79 6d 20 73   "VVA" acronym s
41b0: 74 61 6e 64 73 20 66 6f 72 0a 2a 2a 20 22 56 65  tands for.** "Ve
41c0: 72 69 66 69 63 61 74 69 6f 6e 2c 20 56 61 6c 69  rification, Vali
41d0: 64 61 74 69 6f 6e 2c 20 61 6e 64 20 41 63 63 72  dation, and Accr
41e0: 65 64 69 74 61 74 69 6f 6e 22 2e 20 20 49 6e 20  editation".  In 
41f0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
4200: 0a 2a 2a 20 63 6f 64 65 20 77 69 74 68 69 6e 20  .** code within 
4210: 56 56 41 5f 4f 4e 4c 59 28 29 20 77 69 6c 6c 20  VVA_ONLY() will 
4220: 6f 6e 6c 79 20 72 75 6e 20 64 75 72 69 6e 67 20  only run during 
4230: 76 65 72 69 66 69 63 61 74 69 6f 6e 20 70 72 6f  verification pro
4240: 63 65 73 73 65 73 2e 0a 2a 2f 0a 23 69 66 6e 64  cesses..*/.#ifnd
4250: 65 66 20 4e 44 45 42 55 47 0a 23 20 64 65 66 69  ef NDEBUG.# defi
4260: 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29 20 20  ne VVA_ONLY(X)  
4270: 58 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  X.#else.# define
4280: 20 56 56 41 5f 4f 4e 4c 59 28 58 29 0a 23 65 6e   VVA_ONLY(X).#en
4290: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 41  dif../*.** The A
42a0: 4c 57 41 59 53 20 61 6e 64 20 4e 45 56 45 52 20  LWAYS and NEVER 
42b0: 6d 61 63 72 6f 73 20 73 75 72 72 6f 75 6e 64 20  macros surround 
42c0: 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73 73 69  boolean expressi
42d0: 6f 6e 73 20 77 68 69 63 68 20 0a 2a 2a 20 61 72  ons which .** ar
42e0: 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 61 6c  e intended to al
42f0: 77 61 79 73 20 62 65 20 74 72 75 65 20 6f 72 20  ways be true or 
4300: 66 61 6c 73 65 2c 20 72 65 73 70 65 63 74 69 76  false, respectiv
4310: 65 6c 79 2e 20 20 53 75 63 68 0a 2a 2a 20 65 78  ely.  Such.** ex
4320: 70 72 65 73 73 69 6f 6e 73 20 63 6f 75 6c 64 20  pressions could 
4330: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  be omitted from 
4340: 74 68 65 20 63 6f 64 65 20 63 6f 6d 70 6c 65 74  the code complet
4350: 65 6c 79 2e 20 20 42 75 74 20 74 68 65 79 0a 2a  ely.  But they.*
4360: 2a 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69  * are included i
4370: 6e 20 61 20 66 65 77 20 63 61 73 65 73 20 69 6e  n a few cases in
4380: 20 6f 72 64 65 72 20 74 6f 20 65 6e 68 61 6e 63   order to enhanc
4390: 65 20 74 68 65 20 72 65 73 69 6c 69 65 6e 63 65  e the resilience
43a0: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  .** of SQLite to
43b0: 20 75 6e 65 78 70 65 63 74 65 64 20 62 65 68 61   unexpected beha
43c0: 76 69 6f 72 20 2d 20 74 6f 20 6d 61 6b 65 20 74  vior - to make t
43d0: 68 65 20 63 6f 64 65 20 22 73 65 6c 66 2d 68 65  he code "self-he
43e0: 61 6c 69 6e 67 22 0a 2a 2a 20 6f 72 20 22 64 75  aling".** or "du
43f0: 63 74 69 6c 65 22 20 72 61 74 68 65 72 20 74 68  ctile" rather th
4400: 61 6e 20 62 65 69 6e 67 20 22 62 72 69 74 74 6c  an being "brittl
4410: 65 22 20 61 6e 64 20 63 72 61 73 68 69 6e 67 20  e" and crashing 
4420: 61 74 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  at the first.** 
4430: 68 69 6e 74 20 6f 66 20 75 6e 70 6c 61 6e 6e 65  hint of unplanne
4440: 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
4450: 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
4460: 2c 20 41 4c 57 41 59 53 20 61 6e 64 20 4e 45 56  , ALWAYS and NEV
4470: 45 52 20 61 72 65 20 61 64 64 65 64 20 66 6f 72  ER are added for
4480: 20 64 65 66 65 6e 73 69 76 65 20 63 6f 64 65 2e   defensive code.
4490: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 64 6f 69 6e  .**.** When doin
44a0: 67 20 63 6f 76 65 72 61 67 65 20 74 65 73 74 69  g coverage testi
44b0: 6e 67 20 41 4c 57 41 59 53 20 61 6e 64 20 4e 45  ng ALWAYS and NE
44c0: 56 45 52 20 61 72 65 20 68 61 72 64 2d 63 6f 64  VER are hard-cod
44d0: 65 64 20 74 6f 0a 2a 2a 20 62 65 20 74 72 75 65  ed to.** be true
44e0: 20 61 6e 64 20 66 61 6c 73 65 20 73 6f 20 74 68   and false so th
44f0: 61 74 20 74 68 65 20 75 6e 72 65 61 63 68 61 62  at the unreachab
4500: 6c 65 20 63 6f 64 65 20 74 68 65 6e 20 73 70 65  le code then spe
4510: 63 69 66 79 20 77 69 6c 6c 0a 2a 2a 20 6e 6f 74  cify will.** not
4520: 20 62 65 20 63 6f 75 6e 74 65 64 20 61 73 20 75   be counted as u
4530: 6e 74 65 73 74 65 64 20 63 6f 64 65 2e 0a 2a 2f  ntested code..*/
4540: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53 51 4c  .#if defined(SQL
4550: 49 54 45 5f 43 4f 56 45 52 41 47 45 5f 54 45 53  ITE_COVERAGE_TES
4560: 54 29 0a 23 20 64 65 66 69 6e 65 20 41 4c 57 41  T).# define ALWA
4570: 59 53 28 58 29 20 20 20 20 20 20 28 31 29 0a 23  YS(X)      (1).#
4580: 20 64 65 66 69 6e 65 20 4e 45 56 45 52 28 58 29   define NEVER(X)
4590: 20 20 20 20 20 20 20 28 30 29 0a 23 65 6c 69 66         (0).#elif
45a0: 20 21 64 65 66 69 6e 65 64 28 4e 44 45 42 55 47   !defined(NDEBUG
45b0: 29 0a 23 20 64 65 66 69 6e 65 20 41 4c 57 41 59  ).# define ALWAY
45c0: 53 28 58 29 20 20 20 20 20 20 28 28 58 29 3f 31  S(X)      ((X)?1
45d0: 3a 28 61 73 73 65 72 74 28 30 29 2c 30 29 29 0a  :(assert(0),0)).
45e0: 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52 28 58  # define NEVER(X
45f0: 29 20 20 20 20 20 20 20 28 28 58 29 3f 28 61 73  )       ((X)?(as
4600: 73 65 72 74 28 30 29 2c 31 29 3a 30 29 0a 23 65  sert(0),1):0).#e
4610: 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 41 4c 57  lse.# define ALW
4620: 41 59 53 28 58 29 20 20 20 20 20 20 28 58 29 0a  AYS(X)      (X).
4630: 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52 28 58  # define NEVER(X
4640: 29 20 20 20 20 20 20 20 28 58 29 0a 23 65 6e 64  )       (X).#end
4650: 69 66 0a 0a 2f 2a 0a 2a 2a 20 52 65 74 75 72 6e  if../*.** Return
4660: 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
4670: 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73   if the input is
4680: 20 61 20 69 6e 74 65 67 65 72 20 74 68 61 74 20   a integer that 
4690: 69 73 20 74 6f 6f 20 6c 61 72 67 65 0a 2a 2a 20  is too large.** 
46a0: 74 6f 20 66 69 74 20 69 6e 20 33 32 2d 62 69 74  to fit in 32-bit
46b0: 73 2e 20 20 54 68 69 73 20 6d 61 63 72 6f 20 69  s.  This macro i
46c0: 73 20 75 73 65 64 20 69 6e 73 69 64 65 20 6f 66  s used inside of
46d0: 20 76 61 72 69 6f 75 73 20 74 65 73 74 63 61 73   various testcas
46e0: 65 28 29 0a 2a 2a 20 6d 61 63 72 6f 73 20 74 6f  e().** macros to
46f0: 20 76 65 72 69 66 79 20 74 68 61 74 20 77 65 20   verify that we 
4700: 68 61 76 65 20 74 65 73 74 65 64 20 53 51 4c 69  have tested SQLi
4710: 74 65 20 66 6f 72 20 6c 61 72 67 65 2d 66 69 6c  te for large-fil
4720: 65 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 64  e support..*/.#d
4730: 65 66 69 6e 65 20 49 53 5f 42 49 47 5f 49 4e 54  efine IS_BIG_INT
4740: 28 58 29 20 20 28 28 28 58 29 26 7e 28 69 36 34  (X)  (((X)&~(i64
4750: 29 30 78 66 66 66 66 66 66 66 66 29 21 3d 30 29  )0xffffffff)!=0)
4760: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 63 72  ../*.** The macr
4770: 6f 20 75 6e 6c 69 6b 65 6c 79 28 29 20 69 73 20  o unlikely() is 
4780: 61 20 68 69 6e 74 20 74 68 61 74 20 73 75 72 72  a hint that surr
4790: 6f 75 6e 64 73 20 61 20 62 6f 6f 6c 65 61 6e 0a  ounds a boolean.
47a0: 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 74 68  ** expression th
47b0: 61 74 20 69 73 20 75 73 75 61 6c 6c 79 20 66 61  at is usually fa
47c0: 6c 73 65 2e 20 20 4d 61 63 72 6f 20 6c 69 6b 65  lse.  Macro like
47d0: 6c 79 28 29 20 73 75 72 72 6f 75 6e 64 73 0a 2a  ly() surrounds.*
47e0: 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 65 78 70 72  * a boolean expr
47f0: 65 73 73 69 6f 6e 20 74 68 61 74 20 69 73 20 75  ession that is u
4800: 73 75 61 6c 6c 79 20 74 72 75 65 2e 20 20 47 43  sually true.  GC
4810: 43 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20  C is able to.** 
4820: 75 73 65 20 74 68 65 73 65 20 68 69 6e 74 73 20  use these hints 
4830: 74 6f 20 67 65 6e 65 72 61 74 65 20 62 65 74 74  to generate bett
4840: 65 72 20 63 6f 64 65 2c 20 73 6f 6d 65 74 69 6d  er code, sometim
4850: 65 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e  es..*/.#if defin
4860: 65 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 26 26 20  ed(__GNUC__) && 
4870: 30 0a 23 20 64 65 66 69 6e 65 20 6c 69 6b 65 6c  0.# define likel
4880: 79 28 58 29 20 20 20 20 5f 5f 62 75 69 6c 74 69  y(X)    __builti
4890: 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 31 29 0a  n_expect((X),1).
48a0: 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b 65 6c  # define unlikel
48b0: 79 28 58 29 20 20 5f 5f 62 75 69 6c 74 69 6e 5f  y(X)  __builtin_
48c0: 65 78 70 65 63 74 28 28 58 29 2c 30 29 0a 23 65  expect((X),0).#e
48d0: 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 6c 69 6b  lse.# define lik
48e0: 65 6c 79 28 58 29 20 20 20 20 21 21 28 58 29 0a  ely(X)    !!(X).
48f0: 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b 65 6c  # define unlikel
4900: 79 28 58 29 20 20 21 21 28 58 29 0a 23 65 6e 64  y(X)  !!(X).#end
4910: 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  if../***********
4920: 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69  *** Include sqli
4930: 74 65 33 2e 68 20 69 6e 20 74 68 65 20 6d 69 64  te3.h in the mid
4940: 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49 6e 74  dle of sqliteInt
4950: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .h *************
4960: 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  **/./***********
4970: 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73  *** Begin file s
4980: 71 6c 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a  qlite3.h *******
4990: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
49a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
49b0: 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31 20 53  **/./*.** 2001 S
49c0: 65 70 74 65 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a  eptember 15.**.*
49d0: 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64 69 73  * The author dis
49e0: 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67 68 74  claims copyright
49f0: 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63 65 20   to this source 
4a00: 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63 65 20  code.  In place 
4a10: 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f  of.** a legal no
4a20: 74 69 63 65 2c 20 68 65 72 65 20 69 73 20 61 20  tice, here is a 
4a30: 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20  blessing:.**.** 
4a40: 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f     May you do go
4a50: 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e  od and not evil.
4a60: 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 66  .**    May you f
4a70: 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73 73 20  ind forgiveness 
4a80: 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61 6e 64  for yourself and
4a90: 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72 73 2e   forgive others.
4aa0: 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 73  .**    May you s
4ab0: 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e 65 76  hare freely, nev
4ac0: 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74  er taking more t
4ad0: 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a  han you give..**
4ae0: 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .***************
4af0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4b00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4b10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4b20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68  **********.** Th
4b30: 69 73 20 68 65 61 64 65 72 20 66 69 6c 65 20 64  is header file d
4b40: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
4b50: 66 61 63 65 20 74 68 61 74 20 74 68 65 20 53 51  face that the SQ
4b60: 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20  Lite library.** 
4b70: 70 72 65 73 65 6e 74 73 20 74 6f 20 63 6c 69 65  presents to clie
4b80: 6e 74 20 70 72 6f 67 72 61 6d 73 2e 20 20 49 66  nt programs.  If
4b90: 20 61 20 43 2d 66 75 6e 63 74 69 6f 6e 2c 20 73   a C-function, s
4ba0: 74 72 75 63 74 75 72 65 2c 20 64 61 74 61 74 79  tructure, dataty
4bb0: 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73 74 61  pe,.** or consta
4bc0: 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 20 64 6f  nt definition do
4bd0: 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 69 6e  es not appear in
4be0: 20 74 68 69 73 20 66 69 6c 65 2c 20 74 68 65 6e   this file, then
4bf0: 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 61 20   it is.** not a 
4c00: 70 75 62 6c 69 73 68 65 64 20 41 50 49 20 6f 66  published API of
4c10: 20 53 51 4c 69 74 65 2c 20 69 73 20 73 75 62 6a   SQLite, is subj
4c20: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
4c30: 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c  thout.** notice,
4c40: 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20   and should not 
4c50: 62 65 20 72 65 66 65 72 65 6e 63 65 64 20 62 79  be referenced by
4c60: 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74 20 75   programs that u
4c70: 73 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  se SQLite..**.**
4c80: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 64 65 66   Some of the def
4c90: 69 6e 69 74 69 6f 6e 73 20 74 68 61 74 20 61 72  initions that ar
4ca0: 65 20 69 6e 20 74 68 69 73 20 66 69 6c 65 20 61  e in this file a
4cb0: 72 65 20 6d 61 72 6b 65 64 20 61 73 0a 2a 2a 20  re marked as.** 
4cc0: 22 65 78 70 65 72 69 6d 65 6e 74 61 6c 22 2e 20  "experimental". 
4cd0: 20 45 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   Experimental in
4ce0: 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 72  terfaces are nor
4cf0: 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66 65 61  mally new.** fea
4d00: 74 75 72 65 73 20 72 65 63 65 6e 74 6c 79 20 61  tures recently a
4d10: 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65 2e 20  dded to SQLite. 
4d20: 20 57 65 20 64 6f 20 6e 6f 74 20 61 6e 74 69 63   We do not antic
4d30: 69 70 61 74 65 20 63 68 61 6e 67 65 73 0a 2a 2a  ipate changes.**
4d40: 20 74 6f 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   to experimental
4d50: 20 69 6e 74 65 72 66 61 63 65 73 20 62 75 74 20   interfaces but 
4d60: 72 65 73 65 72 76 65 20 74 68 65 20 72 69 67 68  reserve the righ
4d70: 74 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f 72 20  t to make minor 
4d80: 63 68 61 6e 67 65 73 0a 2a 2a 20 69 66 20 65 78  changes.** if ex
4d90: 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20 75 73  perience from us
4da0: 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64 22 20  e "in the wild" 
4db0: 73 75 67 67 65 73 74 20 73 75 63 68 20 63 68 61  suggest such cha
4dc0: 6e 67 65 73 20 61 72 65 20 70 72 75 64 65 6e 74  nges are prudent
4dd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 66 69  ..**.** The offi
4de0: 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67 65 20  cial C-language 
4df0: 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  API documentatio
4e00: 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69 73 20  n for SQLite is 
4e10: 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f 6d 20  derived.** from 
4e20: 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68 69 73  comments in this
4e30: 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66 69 6c   file.  This fil
4e40: 65 20 69 73 20 74 68 65 20 61 75 74 68 6f 72 69  e is the authori
4e50: 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a 2a 2a  tative source.**
4e60: 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65 20 69   on how SQLite i
4e70: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
4e80: 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61 74 65  ppose to operate
4e90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ..**.** The name
4ea0: 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 75 6e   of this file un
4eb0: 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  der configuratio
4ec0: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69 73 20  n management is 
4ed0: 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a  "sqlite.h.in"..*
4ee0: 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d  * The makefile m
4ef0: 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20  akes some minor 
4f00: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69 73 20  changes to this 
4f10: 66 69 6c 65 20 28 73 75 63 68 20 61 73 20 69 6e  file (such as in
4f20: 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76  serting.** the v
4f30: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61  ersion number) a
4f40: 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73 20 6e  nd changes its n
4f50: 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65 33 2e  ame to "sqlite3.
4f60: 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  h" as.** part of
4f70: 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f 63 65   the build proce
4f80: 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f  ss..*/.#ifndef _
4f90: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 64 65 66 69  SQLITE3_H_.#defi
4fa0: 6e 65 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ne _SQLITE3_H_.#
4fb0: 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72 67 2e  include <stdarg.
4fc0: 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64 65 64  h>     /* Needed
4fd0: 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e 69 74   for the definit
4fe0: 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a  ion of va_list *
4ff0: 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75  /../*.** Make su
5000: 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c 20 74  re we can call t
5010: 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d 20 43  his stuff from C
5020: 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65 78 74  ++..*/.#if 0.ext
5030: 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66  ern "C" {.#endif
5040: 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68 65  .../*.** Add the
5050: 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72   ability to over
5060: 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a 2f  ride 'extern'.*/
5070: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
5080: 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65 20  EXTERN.# define 
5090: 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65 78  SQLITE_EXTERN ex
50a0: 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 23 69 66  tern.#endif..#if
50b0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a  ndef SQLITE_API.
50c0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
50d0: 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  API.#endif.../*.
50e0: 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d  ** These no-op m
50f0: 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20 69  acros are used i
5100: 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72  n front of inter
5110: 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68  faces to mark th
5120: 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ose.** interface
5130: 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70 72  s as either depr
5140: 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72 69  ecated or experi
5150: 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70  mental.  New app
5160: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
5170: 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72  uld not use depr
5180: 65 63 61 74 65 64 20 69 6e 74 65 72 66 61 63 65  ecated interface
5190: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70  s - they are sup
51a0: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72  port for backwar
51b0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
51c0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
51d0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
51e0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
51f0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
5200: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
5210: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
5220: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
5230: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
5240: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
5250: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
5260: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
5270: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
5280: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
5290: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
52a0: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
52b0: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
52c0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
52d0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
52e0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
52f0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
5300: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
5310: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
5320: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
5330: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
5340: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
5350: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
5360: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
5370: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
5380: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
5390: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
53a0: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
53b0: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
53c0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
53d0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
53e0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
53f0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
5400: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
5410: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
5420: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
5430: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
5440: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
5450: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
5460: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
5470: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
5480: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
5490: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
54a0: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
54b0: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
54c0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
54d0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
54e0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
54f0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
5500: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
5510: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
5520: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
5530: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
5540: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
5550: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
5560: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
5570: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
5580: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
5590: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
55a0: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
55b0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
55c0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
55d0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
55e0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
55f0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
5600: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
5610: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
5620: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
5630: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
5640: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
5650: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
5660: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
5670: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
5680: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
5690: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
56a0: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
56b0: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
56c0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
56d0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
56e0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
56f0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
5700: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
5710: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
5720: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
5730: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
5740: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
5750: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
5760: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
5770: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
5780: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
5790: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
57a0: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
57b0: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
57c0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
57d0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
57e0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
57f0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
5800: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
5810: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
5820: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
5830: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
5840: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
5850: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
5860: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
5870: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
5880: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
5890: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
58a0: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
58b0: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
58c0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
58d0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
58e0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
58f0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
5900: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
5910: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
5920: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
5930: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
5940: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
5950: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
5960: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
5970: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
5980: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
5990: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
59a0: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
59b0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
59c0: 20 20 20 20 20 22 33 2e 37 2e 36 2e 33 22 0a 23       "3.7.6.3".#
59d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
59e0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30  RSION_NUMBER 300
59f0: 37 30 30 36 0a 23 64 65 66 69 6e 65 20 53 51 4c  7006.#define SQL
5a00: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20  ITE_SOURCE_ID   
5a10: 20 20 20 22 32 30 31 31 2d 30 35 2d 31 39 20 31     "2011-05-19 1
5a20: 33 3a 32 36 3a 35 34 20 65 64 31 64 61 35 31 30  3:26:54 ed1da510
5a30: 61 32 33 39 65 61 37 36 37 61 30 31 64 63 33 33  a239ea767a01dc33
5a40: 32 62 36 36 37 31 31 39 66 61 33 63 39 30 38 65  2b667119fa3c908e
5a50: 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  "../*.** CAPI3RE
5a60: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
5a70: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
5a80: 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ers.** KEYWORDS:
5a90: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
5aa0: 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  , sqlite3_source
5ab0: 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  id.**.** These i
5ac0: 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64  nterfaces provid
5ad0: 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  e the same infor
5ae0: 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53  mation as the [S
5af0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a  QLITE_VERSION],.
5b00: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
5b10: 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20  ON_NUMBER], and 
5b20: 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49  [SQLITE_SOURCE_I
5b30: 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  D] C preprocesso
5b40: 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20  r macros.** but 
5b50: 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  are associated w
5b60: 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20  ith the library 
5b70: 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68  instead of the h
5b80: 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43  eader file.  ^(C
5b90: 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72  autious.** progr
5ba0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63  ammers might inc
5bb0: 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74  lude assert() st
5bc0: 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69  atements in thei
5bd0: 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  r application to
5be0: 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20  .** verify that 
5bf0: 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
5c00: 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  by these interfa
5c10: 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61  ces match the ma
5c20: 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68  cros in.** the h
5c30: 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20  eader, and thus 
5c40: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
5c50: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a  application is.*
5c60: 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
5c70: 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79  matching library
5c80: 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65   and header file
5c90: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s..**.** <blockq
5ca0: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73  uote><pre>.** as
5cb0: 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69  sert( sqlite3_li
5cc0: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
5cd0: 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  )==SQLITE_VERSIO
5ce0: 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61  N_NUMBER );.** a
5cf0: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71  ssert( strcmp(sq
5d00: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
5d10: 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49  ,SQLITE_SOURCE_I
5d20: 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65  D)==0 );.** asse
5d30: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74  rt( strcmp(sqlit
5d40: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c  e3_libversion(),
5d50: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d  SQLITE_VERSION)=
5d60: 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  =0 );.** </pre><
5d70: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
5d80: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
5d90: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
5da0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74  ng constant cont
5db0: 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66  ains the text of
5dc0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
5dd0: 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68  ].** macro.  ^Th
5de0: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
5df0: 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20  sion() function 
5e00: 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
5e10: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74  r to the.** to t
5e20: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
5e30: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
5e40: 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74  tant.  The sqlit
5e50: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a  e3_libversion().
5e60: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ** function is p
5e70: 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20  rovided for use 
5e80: 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c  in DLLs since DL
5e90: 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20  L users usually 
5ea0: 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64  do not have.** d
5eb0: 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20  irect access to 
5ec0: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  string constants
5ed0: 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e   within the DLL.
5ee0: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
5ef0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
5f00: 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ber() function r
5f10: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
5f20: 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53  r equal to.** [S
5f30: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
5f40: 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c  MBER].  ^The sql
5f50: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
5f60: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
5f70: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
5f80: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
5f90: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
5fa0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
5fb0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
5fc0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
5fd0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a  rocessor macro..
5fe0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
5ff0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
6000: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
6010: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
6020: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
6030: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
6040: 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54 45  rsion[] = SQLITE
6050: 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54 45  _VERSION;.SQLITE
6060: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
6070: 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  *sqlite3_libvers
6080: 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ion(void);.SQLIT
6090: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
60a0: 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65   *sqlite3_source
60b0: 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  id(void);.SQLITE
60c0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
60d0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
60e0: 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  er(void);../*.**
60f0: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
6100: 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70  ime Library Comp
6110: 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20  ilation Options 
6120: 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a  Diagnostics.**.*
6130: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
6140: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
6150: 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  d() function ret
6160: 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20  urns 0 or 1 .** 
6170: 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74 68  indicating wheth
6180: 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65 64  er the specified
6190: 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69   option was defi
61a0: 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69  ned at .** compi
61b0: 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53  le time.  ^The S
61c0: 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61  QLITE_ prefix ma
61d0: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f  y be omitted fro
61e0: 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e  m the .** option
61f0: 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20   name passed to 
6200: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
6210: 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a  ption_used().  .
6220: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
6230: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
6240: 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  _get() function 
6250: 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67  allows iterating
6260: 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73  .** over the lis
6270: 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61  t of options tha
6280: 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20 61  t were defined a
6290: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62  t compile time b
62a0: 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74  y.** returning t
62b0: 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20  he N-th compile 
62c0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69  time option stri
62d0: 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75  ng.  ^If N is ou
62e0: 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73  t of range,.** s
62f0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
6300: 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72  tion_get() retur
6310: 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
6320: 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  r.  ^The SQLITE_
6330: 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f   .** prefix is o
6340: 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20  mitted from any 
6350: 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
6360: 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
6370: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
6380: 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70  t()..**.** ^Supp
6390: 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61 67  ort for the diag
63a0: 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73  nostic functions
63b0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
63c0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a  option_used().**
63d0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d   and sqlite3_com
63e0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
63f0: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20   may be omitted 
6400: 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74 68  by specifying th
6410: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d  e .** [SQLITE_OM
6420: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e  IT_COMPILEOPTION
6430: 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61  _DIAGS] option a
6440: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a  t compile time..
6450: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
6460: 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73  SQL functions [s
6470: 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74  qlite_compileopt
6480: 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ion_used()] and.
6490: 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ** [sqlite_compi
64a0: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20  leoption_get()] 
64b0: 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65  and the [compile
64c0: 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d  _options pragma]
64d0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
64e0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
64f0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51 4c  OPTION_DIAGS.SQL
6500: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
6510: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
6520: 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61  n_used(const cha
6530: 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53 51  r *zOptName);.SQ
6540: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
6550: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
6560: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
6570: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
6580: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
6590: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
65a0: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
65b0: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
65c0: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
65d0: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
65e0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
65f0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
6600: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
6610: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64  led mutexing cod
6620: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f  e omitted due to
6630: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
6640: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70  THREADSAFE] comp
6650: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
6660: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a  being set to 0..
6670: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
6680: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
6690: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
66a0: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
66b0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
66c0: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
66d0: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31  essor macro is 1
66e0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a   or 2, mutexes.*
66f0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
6700: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
6710: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
6720: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
6730: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69  EADSAFE] macro i
6740: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74  s 0, .** the mut
6750: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64  exes are omitted
6760: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d  .  Without the m
6770: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f  utexes, it is no
6780: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65  t safe.** to use
6790: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65   SQLite concurre
67a0: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74  ntly from more t
67b0: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a  han one thread..
67c0: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d  **.** Enabling m
67d0: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20  utexes incurs a 
67e0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
67f0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a  rmance penalty..
6800: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69  ** So if speed i
6810: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f  s of utmost impo
6820: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73  rtance, it makes
6830: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c   sense to disabl
6840: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  e.** the mutexes
6850: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d  .  But for maxim
6860: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78  um safety, mutex
6870: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61  es should be ena
6880: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  bled..** ^The de
6890: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
68a0: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f  s for mutexes to
68b0: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   be enabled..**.
68c0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
68d0: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79  e can be used by
68e0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
68f0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
6900: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  t the.** version
6910: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20   of SQLite that 
6920: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67  it is linking ag
6930: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c  ainst was compil
6940: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64  ed with.** the d
6950: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f  esired setting o
6960: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
6970: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e  READSAFE] macro.
6980: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
6990: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
69a0: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ts on the compil
69b0: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74  e-time mutex set
69c0: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ting.** of the [
69d0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
69e0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c  E] flag.  If SQL
69f0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
6a00: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
6a10: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d  HREADSAFE=1 or =
6a20: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  2 then mutexes a
6a30: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
6a40: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
6a50: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
6a60: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
6a70: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
6a80: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
6a90: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
6aa0: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
6ab0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
6ac0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
6ad0: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
6ae0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
6af0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28  NFIG_MUTEX].  ^(
6b00: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
6b10: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
6b20: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
6b30: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
6b40: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
6b50: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
6b60: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
6b70: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
6b80: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
6b90: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
6ba0: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
6bb0: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
6bc0: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
6bd0: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
6be0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
6bf0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
6c00: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
6c10: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
6c20: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
6c30: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
6c40: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
6c50: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
6c60: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53  nformation..*/.S
6c70: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
6c80: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
6c90: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
6ca0: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
6cb0: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
6cc0: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  dle.** KEYWORDS:
6cd0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
6ce0: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
6cf0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
6d00: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
6d10: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
6d20: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6d30: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
6d40: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
6d50: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
6d60: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
6d70: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
6d80: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
6d90: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
6da0: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
6db0: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
6dc0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
6dd0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
6de0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
6df0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
6e00: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
6e10: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
6e20: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
6e30: 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72 75  ** is its destru
6e40: 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65  ctor.  There are
6e50: 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65   many other inte
6e60: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
6e70: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
6e80: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
6e90: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
6ea0: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
6eb0: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
6ec0: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
6ed0: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
6ee0: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
6ef0: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
6f00: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
6f10: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
6f20: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
6f30: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
6f40: 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a  Integer Types.**
6f50: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
6f60: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  e_int64 sqlite_u
6f70: 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61  int64.**.** Beca
6f80: 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20  use there is no 
6f90: 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77  cross-platform w
6fa0: 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34  ay to specify 64
6fb0: 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70  -bit integer typ
6fc0: 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63  es.** SQLite inc
6fd0: 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66  ludes typedefs f
6fe0: 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  or 64-bit signed
6ff0: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e   and unsigned in
7000: 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  tegers..**.** Th
7010: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
7020: 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  and sqlite3_uint
7030: 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65  64 are the prefe
7040: 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69  rred type defini
7050: 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71  tions..** The sq
7060: 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73  lite_int64 and s
7070: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
7080: 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  es are supported
7090: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a   for backwards.*
70a0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
70b0: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  only..**.** ^The
70c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
70d0: 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  nd sqlite_int64 
70e0: 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20  types can store 
70f0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a  integer values.*
7100: 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33  * between -92233
7110: 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61  72036854775808 a
7120: 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35  nd +922337203685
7130: 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76  4775807 inclusiv
7140: 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
7150: 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73  te3_uint64 and s
7160: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
7170: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
7180: 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20  eger values .** 
7190: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31  between 0 and +1
71a0: 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31  8446744073709551
71b0: 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a  615 inclusive..*
71c0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
71d0: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
71e0: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
71f0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
7200: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
7210: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
7220: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
7230: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
7240: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
7250: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
7260: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
7270: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
7280: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
7290: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
72a0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
72b0: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
72c0: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
72d0: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
72e0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
72f0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
7300: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
7310: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
7320: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
7330: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
7340: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
7350: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
7360: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
7370: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
7380: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
7390: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
73a0: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
73b0: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
73c0: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
73d0: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
73e0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
73f0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
7400: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
7410: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
7420: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
7430: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
7440: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
7450: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
7460: 6f 73 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ose() routine is
7470: 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
7480: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7490: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
74a0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
74b0: 6c 6f 73 65 28 29 20 72 65 74 75 72 6e 20 53 51  lose() return SQ
74c0: 4c 49 54 45 5f 4f 4b 20 69 66 20 74 68 65 20 5b  LITE_OK if the [
74d0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
74e0: 69 73 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  is.** successful
74f0: 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64  ly destroyed and
7500: 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20   all associated 
7510: 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 65  resources are de
7520: 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  allocated..**.**
7530: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
7540: 73 74 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  st [sqlite3_fina
7550: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
7560: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
7570: 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e  tatements].** an
7580: 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  d [sqlite3_blob_
7590: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
75a0: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
75b0: 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  ] associated wit
75c0: 68 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  h.** the [sqlite
75d0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
75e0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
75f0: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
7600: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
7610: 65 33 5f 63 6c 6f 73 65 28 29 20 69 73 20 63 61  e3_close() is ca
7620: 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62  lled on a [datab
7630: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
7640: 74 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a  that still has.*
7650: 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70  * outstanding [p
7660: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
7670: 74 73 5d 20 6f 72 20 5b 42 4c 4f 42 20 68 61 6e  ts] or [BLOB han
7680: 64 6c 65 73 5d 2c 20 74 68 65 6e 20 69 74 20 72  dles], then it r
7690: 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
76a0: 5f 42 55 53 59 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  _BUSY..**.** ^If
76b0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
76c0: 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  )] is invoked wh
76d0: 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ile a transactio
76e0: 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68  n is open,.** th
76f0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  e transaction is
7700: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
7710: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
7720: 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65  * The C paramete
7730: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  r to [sqlite3_cl
7740: 6f 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65 20  ose(C)] must be 
7750: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
7760: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
7770: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
7780: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
7790: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
77a0: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
77b0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
77c0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
77d0: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
77e0: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
77f0: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  sed..** ^Calling
7800: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
7810: 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
7820: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 69 73  nter argument is
7830: 20 61 20 0a 2a 2a 20 68 61 72 6d 6c 65 73 73 20   a .** harmless 
7840: 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45  no-op..*/.SQLITE
7850: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
7860: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
7870: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
7880: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
7890: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
78a0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
78b0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
78c0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
78d0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
78e0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
78f0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
7900: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
7910: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
7920: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
7930: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
7940: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
7950: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
7960: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
7970: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
7980: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
7990: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
79a0: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
79b0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
79c0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
79d0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
79e0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
79f0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
7a00: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
7a10: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
7a20: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
7a30: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
7a40: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
7a50: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
7a60: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
7a70: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
7a80: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
7a90: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
7aa0: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
7ab0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
7ac0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
7ad0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
7ae0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
7af0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
7b00: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
7b10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7b20: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
7b30: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
7b40: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
7b50: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
7b60: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
7b70: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
7b80: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
7b90: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
7ba0: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
7bb0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
7bc0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
7bd0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
7be0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
7bf0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
7c00: 6f 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  o.** to sqlite3_
7c10: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
7c20: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
7c30: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
7c40: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
7c50: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
7c60: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
7c70: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
7c80: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
7c90: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
7ca0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
7cb0: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
7cc0: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
7cd0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
7ce0: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
7cf0: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
7d00: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
7d10: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
7d20: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
7d30: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
7d40: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
7d50: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
7d60: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
7d70: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
7d80: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
7d90: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
7da0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
7db0: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
7dc0: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
7dd0: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
7de0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
7df0: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
7e00: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
7e10: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
7e20: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
7e30: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
7e40: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
7e50: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
7e60: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
7e70: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
7e80: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
7e90: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
7ea0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
7eb0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
7ec0: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f  arameter of.** o
7ed0: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
7ee0: 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72   after the error
7ef0: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
7f00: 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65  is no longer nee
7f10: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ded..** ^If the 
7f20: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
7f30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
7f40: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20  is not NULL and 
7f50: 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63  no errors.** occ
7f60: 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ur, then sqlite3
7f70: 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65  _exec() sets the
7f80: 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20   pointer in its 
7f90: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
7fa0: 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20  .** NULL before 
7fb0: 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
7fc0: 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f   ^If an sqlite3_
7fd0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
7fe0: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
7ff0: 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  , the sqlite3_ex
8000: 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  ec().** routine 
8010: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41  returns SQLITE_A
8020: 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76  BORT without inv
8030: 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61  oking the callba
8040: 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20  ck again and.** 
8050: 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20  without running 
8060: 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53  any subsequent S
8070: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
8080: 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72  *.** ^The 2nd ar
8090: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
80a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
80b0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69  lback function i
80c0: 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
80d0: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
80e0: 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20  e result.  ^The 
80f0: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  3rd argument to 
8100: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
8110: 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ().** callback i
8120: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
8130: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
8140: 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66  s obtained as if
8150: 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
8160: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
8170: 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63  , one for each c
8180: 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65  olumn.  ^If an e
8190: 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72  lement of a.** r
81a0: 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c  esult row is NUL
81b0: 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65  L then the corre
81c0: 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20  sponding string 
81d0: 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a  pointer for the.
81e0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
81f0: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  ) callback is a 
8200: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
8210: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
8220: 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   to the.** sqlit
8230: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
8240: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ck is an array o
8250: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
8260: 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68  rings where each
8270: 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73  .** entry repres
8280: 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ents the name of
8290: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72   corresponding r
82a0: 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20  esult column as 
82b0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
82c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
82d0: 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _name()]..**.** 
82e0: 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61  ^If the 2nd para
82f0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
8300: 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c  _exec() is a NUL
8310: 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69  L pointer, a poi
8320: 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d  nter.** to an em
8330: 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61  pty string, or a
8340: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f   pointer that co
8350: 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74  ntains only whit
8360: 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a  espace and/or .*
8370: 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20  * SQL comments, 
8380: 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74  then no SQL stat
8390: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
83a0: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74  ated and the dat
83b0: 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20  abase.** is not 
83c0: 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  changed..**.** R
83d0: 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a  estrictions:.**.
83e0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
83f0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
8400: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
8410: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
8420: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
8430: 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20  ec().**      is 
8440: 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e  a valid and open
8450: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
8460: 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20  ction]..** <li> 
8470: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
8480: 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b  must not close [
8490: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
84a0: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
84b0: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73  y.**      the 1s
84c0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
84d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
84e0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
84f0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
8500: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
8510: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
8520: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73  modify the SQL s
8530: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61  tatement text pa
8540: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20  ssed into.**    
8550: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65    the 2nd parame
8560: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  ter of sqlite3_e
8570: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
8580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
8590: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  nning..** </ul>.
85a0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
85b0: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
85c0: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
85d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
85e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
85f0: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
8600: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
8610: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
8620: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8630: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
8640: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
8650: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
8660: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
8670: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
8680: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
8690: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
86a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
86b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
86c0: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
86d0: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
86e0: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
86f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8700: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
8710: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
8720: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
8730: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
8740: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
8750: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
8760: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
8770: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
8780: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
8790: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
87a0: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
87b0: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
87c0: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
87d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
87e0: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
87f0: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
8800: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
8810: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
8820: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
8830: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
8840: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
8850: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
8860: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
8870: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
8880: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
8890: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
88a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
88b0: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
88c0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
88d0: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
88e0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
88f0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
8900: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
8910: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
8920: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
8930: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
8940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
8950: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
8960: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
8970: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
8980: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8990: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
89a0: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
89b0: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
89c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
89d0: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
89e0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
89f0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
8a00: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
8a10: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
8a20: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
8a30: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
8a40: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
8a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
8a60: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
8a70: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
8a80: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
8a90: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
8aa0: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
8ab0: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
8ac0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
8ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
8ae0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
8af0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
8b00: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
8b10: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
8b20: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
8b30: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
8b40: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
8b50: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
8b60: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
8b70: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
8b80: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
8b90: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
8ba0: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
8bb0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8bc0: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
8bd0: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
8be0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
8bf0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
8c00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
8c10: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
8c20: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
8c30: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
8c40: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
8c50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
8c60: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
8c70: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
8c80: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
8c90: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
8ca0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
8cb0: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
8cc0: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
8cd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8ce0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
8cf0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
8d00: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
8d10: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
8d20: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
8d30: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
8d40: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
8d50: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
8d60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
8d70: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
8d80: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
8d90: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
8da0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8db0: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
8dc0: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
8dd0: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
8de0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
8df0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
8e00: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
8e10: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
8e20: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
8e30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8e40: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
8e50: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
8e60: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
8e70: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
8e80: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
8e90: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
8ea0: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
8eb0: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
8ec0: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
8ed0: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
8ee0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
8ef0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
8f00: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
8f10: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
8f20: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
8f30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8f40: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
8f50: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
8f60: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
8f70: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
8f80: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
8f90: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
8fa0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
8fb0: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
8fc0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
8fd0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
8fe0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
8ff0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
9000: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
9010: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
9020: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
9030: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
9040: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
9050: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
9060: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9070: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
9080: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
9090: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
90a0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
90b0: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
90c0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
90d0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
90e0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
90f0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
9100: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
9110: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
9120: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
9130: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
9140: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
9150: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
9160: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
9170: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
9180: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
9190: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
91a0: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
91b0: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
91c0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
91d0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
91e0: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
91f0: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
9200: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
9210: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
9220: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
9230: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
9240: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
9250: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
9260: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
9270: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
9280: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
9290: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
92a0: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
92b0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
92c0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
92d0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
92e0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
92f0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
9300: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
9310: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
9320: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
9330: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
9340: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
9350: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
9360: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
9370: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
9380: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9390: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
93a0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
93b0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
93c0: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
93d0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
93e0: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
93f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
9400: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
9410: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
9420: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
9430: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
9440: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
9450: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
9460: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
9470: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
9480: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
9490: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
94a0: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
94b0: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
94c0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
94d0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
94e0: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
94f0: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
9500: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
9510: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
9520: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
9530: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9540: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
9550: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
9560: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
9570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9580: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
9590: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
95a0: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
95b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
95c0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
95d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
95e0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
95f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9600: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
9610: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9620: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
9630: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9640: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
9650: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9660: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
9670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
9680: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
9690: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
96a0: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
96b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
96c0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
96d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
96e0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
96f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
9700: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
9710: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
9720: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
9730: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
9740: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
9750: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
9760: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
9770: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
9780: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
9790: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
97a0: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
97b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
97c0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
97d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
97e0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
97f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
9800: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
9810: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
9820: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
9830: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
9840: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
9850: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
9860: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
9870: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
9880: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
9890: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
98a0: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
98b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
98c0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
98d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
98e0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
98f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
9900: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
9910: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
9920: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
9930: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
9940: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
9950: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
9960: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
9970: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
9980: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
9990: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
99a0: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
99b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
99c0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
99d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
99e0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
99f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
9a00: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
9a10: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
9a20: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
9a30: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
9a40: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
9a50: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
9a60: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
9a70: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
9a80: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
9a90: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
9aa0: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
9ab0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
9ac0: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
9ad0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
9ae0: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  EN | (1<<8))../*
9af0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
9b00: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
9b10: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
9b20: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
9b30: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
9b40: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
9b50: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
9b60: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9b70: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
9b80: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
9b90: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
9ba0: 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  r to the xOpen m
9bb0: 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20  ethod of the.** 
9bc0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
9bd0: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
9be0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
9bf0: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
9c00: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
9c10: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9c20: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9c30: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
9c40: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
9c50: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
9c60: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9c70: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9c80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
9c90: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
9ca0: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
9cb0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9cc0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9cd0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
9ce0: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
9cf0: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
9d00: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9d10: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
9d20: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
9d30: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
9d40: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9d50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
9d60: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
9d70: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
9d80: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9d90: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
9da0: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
9db0: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
9dc0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9dd0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
9de0: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
9df0: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
9e00: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9e10: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
9e20: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
9e30: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
9e40: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9e50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
9e60: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
9e70: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
9e80: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9e90: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
9ea0: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
9eb0: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
9ec0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9ed0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
9ee0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
9ef0: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
9f00: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9f10: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
9f20: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
9f30: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
9f40: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9f50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
9f60: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
9f70: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
9f80: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9f90: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9fa0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
9fb0: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
9fc0: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
9fd0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9fe0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9ff0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
a000: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
a010: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
a020: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a030: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a040: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
a050: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
a060: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
a070: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a080: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a090: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
a0a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
a0b0: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
a0c0: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
a0d0: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
a0e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
a0f0: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
a100: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
a110: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
a120: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
a130: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
a140: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
a150: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
a160: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
a170: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
a180: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
a190: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74   vector of the t
a1a0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
a1b0: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
a1c0: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
a1d0: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
a1e0: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
a1f0: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
a200: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
a210: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
a220: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
a230: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
a240: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
a250: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
a260: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
a270: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
a280: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
a290: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a2a0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
a2b0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
a2c0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
a2d0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
a2e0: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
a2f0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
a300: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
a310: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
a320: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
a330: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
a340: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
a350: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
a360: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
a370: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
a380: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
a390: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
a3a0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
a3b0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
a3c0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
a3d0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
a3e0: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
a3f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
a400: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
a410: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
a420: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
a430: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
a440: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
a450: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
a460: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
a470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
a480: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
a490: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
a4a0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
a4b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
a4c0: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
a4d0: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
a4e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
a4f0: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
a500: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
a510: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
a520: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a530: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
a540: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
a550: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
a560: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
a570: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a580: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
a590: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
a5a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
a5b0: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
a5c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
a5d0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
a5e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
a5f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a600: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
a610: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
a620: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
a630: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a640: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
a650: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
a660: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
a670: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
a680: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
a690: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
a6a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
a6b0: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
a6c0: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
a6d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
a6e0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
a6f0: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
a700: 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  800../*.** CAPI3
a710: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
a720: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
a730: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
a740: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
a750: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
a760: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
a770: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
a780: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
a790: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
a7a0: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
a7b0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
a7c0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
a7d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a7e0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
a7f0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
a800: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
a810: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
a820: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
a830: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
a840: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
a850: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
a860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a870: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
a880: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
a890: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
a8a0: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
a8b0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
a8c0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
a8d0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
a8e0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
a8f0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
a900: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
a910: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
a920: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
a930: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
a940: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
a950: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
a960: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
a970: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
a980: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
a990: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
a9a0: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
a9b0: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
a9c0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
a9d0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
a9e0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
a9f0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
aa00: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
aa10: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
aa20: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
aa30: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
aa40: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
aa50: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
aa60: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
aa70: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
aa80: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
aa90: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
aaa0: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
aab0: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
aac0: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
aad0: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
aae0: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
aaf0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
ab00: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
ab10: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
ab20: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
ab30: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
ab40: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
ab50: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
ab60: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
ab70: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
ab80: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
ab90: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
aba0: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
abb0: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
abc0: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
abd0: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
abe0: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
abf0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
ac00: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
ac10: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
ac20: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
ac30: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
ac40: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
ac50: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
ac60: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
ac70: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
ac80: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
ac90: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
aca0: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
acb0: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
acc0: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
acd0: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
ace0: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
acf0: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
ad00: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
ad10: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
ad20: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
ad30: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
ad40: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
ad50: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
ad60: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
ad70: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
ad80: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
ad90: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
ada0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
adb0: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
adc0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
add0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
ade0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
adf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
ae00: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
ae10: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
ae20: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
ae30: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
ae40: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
ae50: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
ae60: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
ae70: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
ae80: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
ae90: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
aea0: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
aeb0: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
aec0: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
aed0: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
aee0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
aef0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
af00: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
af10: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
af20: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
af30: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
af40: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
af50: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
af60: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
af70: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
af80: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
af90: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
afa0: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
afb0: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
afc0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
afd0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
afe0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
aff0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
b000: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
b010: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
b020: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
b030: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
b040: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
b050: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
b060: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
b070: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
b080: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
b090: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
b0a0: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
b0b0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70  sqlite3_vfs] xOp
b0c0: 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  en method popula
b0d0: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
b0e0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
b0f0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
b100: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
b110: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
b120: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
b130: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
b140: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
b150: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
b160: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
b170: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
b180: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
b190: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
b1a0: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
b1b0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
b1c0: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
b1d0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
b1e0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
b1f0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
b200: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
b210: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
b220: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
b230: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
b240: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
b250: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
b260: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
b270: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
b280: 76 65 6e 20 69 66 20 74 68 65 20 78 4f 70 65 6e  ven if the xOpen
b290: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
b2a0: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
b2b0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
b2c0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
b2d0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
b2e0: 20 61 20 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a   a failed xOpen.
b2f0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 78 4f  ** is for the xO
b300: 70 65 6e 20 74 6f 20 73 65 74 20 74 68 65 20 73  pen to set the s
b310: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
b320: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20  hods element to 
b330: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
b340: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
b350: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
b360: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
b370: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
b380: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
b390: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
b3a0: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
b3b0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
b3c0: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
b3d0: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
b3e0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
b3f0: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
b400: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
b410: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
b420: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
b430: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
b440: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
b450: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
b460: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
b470: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
b480: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
b490: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
b4a0: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
b4b0: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
b4c0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
b4d0: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
b4e0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
b4f0: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
b500: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
b510: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
b520: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
b530: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
b540: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
b550: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
b560: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
b570: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
b580: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
b590: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
b5a0: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
b5b0: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
b5c0: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
b5d0: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
b5e0: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
b5f0: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
b600: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
b610: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
b620: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
b630: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
b640: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
b650: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
b660: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
b670: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
b680: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
b690: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
b6a0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
b6b0: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
b6c0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
b6d0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
b6e0: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
b6f0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
b700: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
b710: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
b720: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
b730: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
b740: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
b750: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
b760: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
b770: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
b780: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
b790: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
b7a0: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
b7b0: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
b7c0: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
b7d0: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
b7e0: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
b7f0: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
b800: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
b810: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
b820: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
b830: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
b840: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
b850: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
b860: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
b870: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
b880: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
b890: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
b8a0: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
b8b0: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
b8c0: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
b8d0: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
b8e0: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
b8f0: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
b900: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
b910: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
b920: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
b930: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
b940: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
b950: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
b960: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
b970: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
b980: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
b990: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
b9a0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
b9b0: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
b9c0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
b9d0: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
b9e0: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
b9f0: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
ba00: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
ba10: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
ba20: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
ba30: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
ba40: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
ba50: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
ba60: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
ba70: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
ba80: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
ba90: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
baa0: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
bab0: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
bac0: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
bad0: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
bae0: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
baf0: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
bb00: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
bb10: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
bb20: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
bb30: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
bb40: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
bb50: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
bb60: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
bb70: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
bb80: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
bb90: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
bba0: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
bbb0: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
bbc0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
bbd0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
bbe0: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
bbf0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
bc00: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
bc10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
bc20: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
bc30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
bc40: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
bc50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
bc60: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
bc70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
bc80: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
bc90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
bca0: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
bcb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
bcc0: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
bcd0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
bce0: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
bcf0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
bd00: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
bd10: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
bd20: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
bd30: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
bd40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
bd50: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
bd60: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
bd70: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
bd80: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
bd90: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
bda0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
bdb0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
bdc0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
bdd0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
bde0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
bdf0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
be00: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
be10: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
be20: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
be30: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
be40: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
be50: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
be60: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
be70: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
be80: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
be90: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
bea0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
beb0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
bec0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
bed0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
bee0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
bef0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
bf00: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
bf10: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
bf20: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
bf30: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
bf40: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
bf50: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
bf60: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
bf70: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
bf80: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
bf90: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
bfa0: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
bfb0: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
bfc0: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
bfd0: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
bfe0: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
bff0: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
c000: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
c010: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
c020: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
c030: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
c040: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
c050: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
c060: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
c070: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
c080: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
c090: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
c0a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
c0b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
c0c0: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
c0d0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
c0e0: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
c0f0: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
c100: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
c110: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
c120: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
c130: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
c140: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
c150: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
c160: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
c170: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
c180: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
c190: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
c1a0: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
c1b0: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
c1c0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
c1d0: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
c1e0: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
c1f0: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
c200: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
c210: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
c220: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
c230: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
c240: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
c250: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
c260: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
c270: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
c280: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
c290: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
c2a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
c2b0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
c2c0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
c2d0: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
c2e0: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
c2f0: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
c300: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
c310: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
c320: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
c330: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
c340: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
c350: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
c360: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
c370: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
c380: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
c390: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
c3a0: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
c3b0: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
c3c0: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
c3d0: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
c3e0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
c3f0: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
c400: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
c410: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
c420: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
c430: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
c440: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
c450: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
c460: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
c470: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
c480: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f  version 2 */.  /
c490: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
c4a0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
c4b0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
c4c0: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
c4d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
c4e0: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
c4f0: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
c500: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
c510: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
c520: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
c530: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
c540: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
c550: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
c560: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
c570: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
c580: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
c590: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
c5a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c5b0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
c5c0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
c5d0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
c5e0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
c5f0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
c600: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
c610: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
c620: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
c630: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
c640: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
c650: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
c660: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
c670: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
c680: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
c690: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
c6a0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
c6b0: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
c6c0: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
c6d0: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
c6e0: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
c6f0: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
c700: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
c710: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
c720: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
c730: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
c740: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
c750: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
c760: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
c770: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
c780: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
c790: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
c7a0: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
c7b0: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
c7c0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
c7d0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
c7e0: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
c7f0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
c800: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
c810: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
c820: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
c830: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
c840: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
c850: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
c860: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
c870: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
c880: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
c890: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
c8a0: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
c8b0: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
c8c0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
c8d0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
c8e0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c8f0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
c900: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
c910: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
c920: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
c930: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
c940: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
c950: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
c960: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
c970: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
c980: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
c990: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
c9a0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
c9b0: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
c9c0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
c9d0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
c9e0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
c9f0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
ca00: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
ca10: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
ca20: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
ca30: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
ca40: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
ca50: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
ca60: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
ca70: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
ca80: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
ca90: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
caa0: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
cab0: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ems..**.** The [
cac0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
cad0: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
cae0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
caf0: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
cb00: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
cb10: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
cb20: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
cb30: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
cb40: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
cb50: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
cb60: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
cb70: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
cb80: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
cb90: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
cba0: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ..**.** ^(The [S
cbb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
cbc0: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
cbd0: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
cbe0: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
cbf0: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
cc00: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
cc10: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
cc20: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
cc30: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
cc40: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
cc50: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
cc60: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
cc70: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
cc80: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
cc90: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
cca0: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
ccb0: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
ccc0: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
ccd0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
cce0: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
ccf0: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
cd00: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
cd10: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
cd20: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
cd30: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
cd40: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
cd50: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
cd60: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
cd70: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
cd80: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
cd90: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
cda0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
cdb0: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
cdc0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
cdd0: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a  ecialized VFSes.
cde0: 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  ** that do requi
cdf0: 72 65 20 69 74 2e 20 20 0a 2a 2f 0a 23 64 65 66  re it.  .*/.#def
ce00: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ce10: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
ce20: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
ce30: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
ce40: 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66  FILE      2.#def
ce50: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
ce60: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
ce70: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
ce80: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
ce90: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
cea0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ceb0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
cec0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
ced0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
cee0: 49 5a 45 20 20 20 20 20 20 20 36 0a 23 64 65 66  IZE       6.#def
cef0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cf00: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
cf10: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
cf20: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
cf30: 49 54 54 45 44 20 20 20 20 20 38 0a 0a 0a 2f 2a  ITTED     8.../*
cf40: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
cf50: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
cf60: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
cf70: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
cf80: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
cf90: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
cfa0: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
cfb0: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
cfc0: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
cfd0: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
cfe0: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
cff0: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
d000: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
d010: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
d020: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
d030: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
d040: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
d050: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
d060: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
d070: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
d080: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
d090: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
d0a0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
d0b0: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
d0c0: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
d0d0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
d0e0: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e   Object.**.** An
d0f0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
d100: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
d110: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
d120: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
d130: 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20  n.** the SQLite 
d140: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64  core and the und
d150: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
d160: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22  g system.  The "
d170: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  vfs".** in the n
d180: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63  ame of the objec
d190: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69  t stands for "vi
d1a0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
d1b0: 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  m"..**.** The va
d1c0: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
d1d0: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
d1e0: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
d1f0: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
d200: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
d210: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
d220: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
d230: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
d240: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
d250: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
d260: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
d270: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
d280: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
d290: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
d2a0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
d2b0: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
d2c0: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
d2d0: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
d2e0: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
d2f0: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
d300: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
d310: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
d320: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
d330: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
d340: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
d350: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
d360: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
d370: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
d380: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
d390: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
d3a0: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
d3b0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
d3c0: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
d3d0: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
d3e0: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
d3f0: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
d400: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
d410: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
d420: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
d430: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
d440: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
d450: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
d460: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
d470: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
d480: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
d490: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
d4a0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
d4b0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
d4c0: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
d4d0: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
d4e0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
d4f0: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
d500: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
d510: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
d520: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
d530: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
d540: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
d550: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
d560: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
d570: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
d580: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
d590: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
d5a0: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
d5b0: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
d5c0: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
d5d0: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
d5e0: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
d5f0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
d600: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
d610: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
d620: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
d630: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
d640: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
d650: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
d660: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
d670: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
d680: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
d690: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
d6a0: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
d6b0: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
d6c0: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
d6d0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  .**.** ^SQLite g
d6e0: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
d6f0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
d700: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a  ameter to xOpen.
d710: 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ** is either a N
d720: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73  ULL pointer or s
d730: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a  tring obtained.*
d740: 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68  * from xFullPath
d750: 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f  name() with an o
d760: 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61  ptional suffix a
d770: 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73  dded..** ^If a s
d780: 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74  uffix is added t
d790: 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  o the zFilename 
d7a0: 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69  parameter, it wi
d7b0: 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66  ll.** consist of
d7c0: 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68   a single "-" ch
d7d0: 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64  aracter followed
d7e0: 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e   by no more than
d7f0: 0a 2a 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d 65  .** 10 alphanume
d800: 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63  ric and/or "-" c
d810: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53  haracters..** ^S
d820: 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75  QLite further gu
d830: 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a  arantees that.**
d840: 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
d850: 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e   be valid and un
d860: 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43  changed until xC
d870: 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c  lose() is.** cal
d880: 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20  led. Because of 
d890: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
d8a0: 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tence,.** the [s
d8b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
d8c0: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
d8d0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
d8e0: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
d8f0: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
d900: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
d910: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
d920: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
d930: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
d940: 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  o xOpen is a NUL
d950: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
d960: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
d970: 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ent its own temp
d980: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
d990: 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65  he file.  ^Whene
d9a0: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
d9b0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
d9c0: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
d9d0: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
d9e0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
d9f0: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
da00: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
da10: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
da20: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  LOSE]..**.** The
da30: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
da40: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
da50: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
da60: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
da70: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
da80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
da90: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
daa0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
dab0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
dac0: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
dad0: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
dae0: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
daf0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
db00: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
db10: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20  EN_CREATE]. .** 
db20: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
db30: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
db40: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
db50: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
db60: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
db70: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20  OPEN_READONLY]. 
db80: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
db90: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
dba0: 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51   set..**.** ^(SQ
dbb0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
dbc0: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
dbd0: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
dbe0: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
dbf0: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
dc00: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
dc10: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
dc20: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
dc30: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
dc40: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
dc50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
dc60: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
dc70: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
dc80: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
dc90: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
dca0: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
dcb0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
dcc0: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
dcd0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
dce0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
dcf0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
dd00: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
dd10: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
dd20: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57    [SQLITE_OPEN_W
dd30: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  AL].** </ul>)^.*
dd40: 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f  *.** The file I/
dd50: 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  O implementation
dd60: 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a   can use the obj
dd70: 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74  ect type flags t
dd80: 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  o.** change the 
dd90: 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74  way it deals wit
dda0: 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78  h files.  For ex
ddb0: 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
ddc0: 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f  ation.** that do
ddd0: 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75  es not care abou
dde0: 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79  t crash recovery
ddf0: 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67   or rollback mig
de00: 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f  ht make.** the o
de10: 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c  pen of a journal
de20: 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20   file a no-op.  
de30: 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a  Writes to this j
de40: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20  ournal would.** 
de50: 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20  also be no-ops, 
de60: 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20  and any attempt 
de70: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
de80: 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  nal would return
de90: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  .** SQLITE_IOERR
dea0: 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d  .  Or the implem
deb0: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72  entation might r
dec0: 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20  ecognize that a 
ded0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
dee0: 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70   will be doing p
def0: 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74  age-aligned sect
df00: 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69  or reads and wri
df10: 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a  tes in a random.
df20: 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74  ** order and set
df30: 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73   up its I/O subs
df40: 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c  ystem accordingl
df50: 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  y..**.** SQLite 
df60: 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
df70: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
df80: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
df90: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a   xOpen method:.*
dfa0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
dfb0: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  > [SQLITE_OPEN_D
dfc0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
dfd0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
dfe0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a  EN_EXCLUSIVE].**
dff0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
e000: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
e010: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
e020: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
e030: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
e040: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
e050: 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b   closed.  ^The [
e060: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
e070: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
e080: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
e090: 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64  MP databases and
e0a0: 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c   their journals,
e0b0: 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61   transient.** da
e0c0: 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62  tabases, and sub
e0d0: 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20  journals..**.** 
e0e0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
e0f0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
e100: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
e110: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
e120: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
e130: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
e140: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
e150: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
e160: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
e170: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
e180: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
e190: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
e1a0: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
e1b0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
e1c0: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
e1d0: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
e1e0: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
e1f0: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
e200: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
e210: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
e220: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
e230: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
e240: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
e250: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
e260: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
e270: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
e280: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
e290: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
e2a0: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
e2b0: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  access..**.** ^A
e2c0: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
e2d0: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
e2e0: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
e2f0: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
e300: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
e310: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
e320: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
e330: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
e340: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65  t to xOpen.  The
e350: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
e360: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
e370: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
e380: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
e390: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
e3a0: 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a   in.  Note that.
e3b0: 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  ** the xOpen met
e3c0: 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65  hod must set the
e3d0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
e3e0: 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72  ethods to either
e3f0: 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c  .** a valid [sql
e400: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
e410: 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55   object or to NU
e420: 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20  LL.  xOpen must 
e430: 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20  do.** this even 
e440: 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c  if the open fail
e450: 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63  s.  SQLite expec
e460: 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69  ts that the sqli
e470: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
e480: 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c  s.** element wil
e490: 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72  l be valid after
e4a0: 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72   xOpen returns r
e4b0: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
e4c0: 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66   success.** or f
e4d0: 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f  ailure of the xO
e4e0: 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  pen call..**.** 
e4f0: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
e500: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
e510: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
e520: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
e530: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
e540: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
e550: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
e560: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
e570: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
e580: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
e590: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
e5a0: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
e5b0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
e5c0: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
e5d0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
e5e0: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
e5f0: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
e600: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
e610: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
e620: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
e630: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
e640: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
e650: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
e660: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
e670: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
e680: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
e690: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
e6a0: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
e6b0: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
e6c0: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
e6d0: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
e6e0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
e6f0: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
e700: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
e710: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
e720: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
e730: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
e740: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
e750: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
e760: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
e770: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
e780: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
e790: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
e7a0: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
e7b0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
e7c0: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
e7d0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
e7e0: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
e7f0: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
e800: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
e810: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
e820: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
e830: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
e840: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
e850: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
e860: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
e870: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
e880: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
e890: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
e8a0: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
e8b0: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
e8c0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
e8d0: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
e8e0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
e8f0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
e900: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
e910: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
e920: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
e930: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
e940: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
e950: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
e960: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
e970: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
e980: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
e990: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
e9a0: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
e9b0: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
e9c0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
e9d0: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
e9e0: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
e9f0: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
ea00: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
ea10: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
ea20: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
ea30: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
ea40: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
ea50: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
ea60: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
ea70: 72 20 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38  r multipled by 8
ea80: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
ea90: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
eaa0: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
eab0: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
eac0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
ead0: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
eae0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
eaf0: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
eb00: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
eb10: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
eb20: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
eb30: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
eb40: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
eb50: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
eb60: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
eb70: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
eb80: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
eb90: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
eba0: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
ebb0: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
ebc0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
ebd0: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
ebe0: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
ebf0: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
ec00: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
ec10: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
ec20: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
ec30: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
ec40: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
ec50: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
ec60: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
ec70: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
ec80: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
ec90: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
eca0: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
ecb0: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
ecc0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
ecd0: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
ece0: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
ecf0: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
ed00: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
ed10: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
ed20: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
ed30: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
ed40: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
ed50: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
ed60: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
ed70: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
ed80: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
ed90: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
eda0: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
edb0: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
edc0: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
edd0: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
ede0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
edf0: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
ee00: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
ee10: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
ee20: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
ee30: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
ee40: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
ee50: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
ee60: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
ee70: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
ee80: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
ee90: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
eea0: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
eeb0: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
eec0: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
eed0: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
eee0: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
eef0: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
ef00: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
ef10: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
ef20: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
ef30: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
ef40: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
ef50: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
ef60: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
ef70: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
ef80: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
ef90: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
efa0: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
efb0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
efc0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
efd0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
efe0: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
eff0: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
f000: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
f010: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
f020: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
f030: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
f040: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
f050: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
f060: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
f070: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
f080: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
f090: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
f0a0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
f0b0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
f0c0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
f0d0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
f0e0: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
f0f0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
f100: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
f110: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
f120: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
f130: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
f140: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
f150: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
f160: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
f170: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
f180: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
f190: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
f1a0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
f1b0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
f1c0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
f1d0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
f1e0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
f1f0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
f200: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
f210: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
f220: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
f230: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
f240: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
f250: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
f260: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
f270: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
f280: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
f290: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
f2a0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
f2b0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
f2c0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
f2d0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
f2e0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
f2f0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
f300: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
f310: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
f320: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
f330: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
f340: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
f350: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
f360: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
f370: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
f380: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
f390: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
f3a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
f3b0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
f3c0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
f3d0: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
f3e0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
f3f0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
f400: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
f410: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
f420: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
f430: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
f440: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
f450: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
f460: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
f470: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
f480: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
f490: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
f4a0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
f4b0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
f4c0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
f4d0: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
f4e0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
f4f0: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
f500: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
f510: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
f520: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
f530: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
f540: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
f550: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
f560: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
f570: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
f580: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
f590: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
f5a0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
f5b0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
f5c0: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
f5d0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
f5e0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f5f0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
f600: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
f610: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
f620: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
f630: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
f640: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
f650: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
f660: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
f670: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
f680: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
f690: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
f6a0: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
f6b0: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
f6c0: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
f6d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
f6e0: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
f6f0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
f700: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
f710: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
f720: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
f730: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
f740: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
f750: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
f760: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
f770: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
f780: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
f790: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
f7a0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
f7b0: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
f7c0: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
f7d0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
f7e0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
f7f0: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
f800: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
f810: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
f820: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
f830: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
f840: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f850: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
f860: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
f870: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
f880: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
f890: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
f8a0: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
f8b0: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
f8c0: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
f8d0: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
f8e0: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
f8f0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
f900: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
f910: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
f920: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
f930: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
f940: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
f950: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
f960: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
f970: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
f980: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
f990: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
f9a0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
f9b0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f9c0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
f9d0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
f9e0: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
f9f0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
fa00: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
fa10: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
fa20: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
fa30: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
fa40: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
fa50: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
fa60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
fa70: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
fa80: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
fa90: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
faa0: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
fab0: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
fac0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
fad0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
fae0: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
faf0: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
fb00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
fb10: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
fb20: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
fb30: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
fb40: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
fb50: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
fb60: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
fb70: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
fb80: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
fb90: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
fba0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
fbb0: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
fbc0: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
fbd0: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
fbe0: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
fbf0: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
fc00: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
fc10: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
fc20: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
fc30: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
fc40: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
fc50: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
fc60: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
fc70: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
fc80: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
fc90: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
fca0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
fcb0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
fcc0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
fcd0: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
fce0: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
fcf0: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
fd00: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
fd10: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
fd20: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
fd30: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
fd40: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
fd50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
fd60: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
fd70: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
fd80: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
fd90: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
fda0: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
fdb0: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
fdc0: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
fdd0: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
fde0: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
fdf0: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
fe00: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
fe10: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
fe20: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
fe30: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
fe40: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
fe50: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
fe60: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
fe70: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
fe80: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
fe90: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
fea0: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
feb0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
fec0: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
fed0: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
fee0: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
fef0: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
ff00: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
ff10: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
ff20: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
ff30: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
ff40: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
ff50: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
ff60: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
ff70: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
ff80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ff90: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
ffa0: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
ffb0: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
ffc0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
ffd0: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
ffe0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fff0: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
10000 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
10010 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
10020 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
10030 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
10040 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
10050 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
10060 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
10070 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
10080 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
10090 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
100a0 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
100b0 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
100c0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
100d0 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
100e0 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
100f0 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
10100 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
10110 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
10120 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
10130 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
10140 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
10150 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
10160 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
10170 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
10180 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
10190 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
101a0 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
101b0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
101c0 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
101d0 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
101e0 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
101f0 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
10200 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
10210 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10220 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
10230 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
10240 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
10250 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
10260 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
10270 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
10280 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
10290 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
102a0 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
102b0 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
102c0 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
102d0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
102e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
102f0 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
10300 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
10310 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
10320 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
10330 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
10340 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
10350 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
10360 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
10370 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
10380 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10390 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
103a0 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
103b0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
103c0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
103d0 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
103e0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
103f0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
10400 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10410 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
10420 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
10430 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10440 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
10450 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
10460 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
10470 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
10480 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
10490 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
104a0 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
104b0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
104c0 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
104d0 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
104e0 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
104f0 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
10500 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
10510 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
10520 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
10530 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
10540 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
10550 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
10560 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
10570 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
10580 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
10590 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
105a0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
105b0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
105c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
105d0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
105e0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
105f0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
10600 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
10610 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
10620 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10630 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
10640 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
10650 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
10660 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
10670 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
10680 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
10690 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
106a0 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
106b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
106c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
106d0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
106e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
106f0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
10700 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
10710 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
10720 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
10730 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
10740 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
10750 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
10760 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
10770 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10780 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
10790 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
107a0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
107b0 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
107c0 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
107d0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
107e0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
107f0 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
10800 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
10810 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
10820 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
10830 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
10840 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
10850 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
10860 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10870 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
10880 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
10890 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
108a0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
108b0 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
108c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
108d0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
108e0 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
108f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
10900 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
10910 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
10920 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
10930 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
10940 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
10950 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
10960 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
10970 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
10980 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
10990 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
109a0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
109b0 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
109c0 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
109d0 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
109e0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
109f0 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
10a00 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
10a10 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
10a20 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
10a30 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
10a40 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
10a50 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10a60 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
10a70 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
10a80 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
10a90 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
10aa0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
10ab0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
10ac0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
10ad0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
10ae0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
10af0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
10b00 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
10b10 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
10b20 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
10b30 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
10b40 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
10b50 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
10b60 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
10b70 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
10b80 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
10b90 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
10ba0 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
10bb0 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
10bc0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
10bd0 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
10be0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
10bf0 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
10c00 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
10c10 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
10c20 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
10c30 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
10c40 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
10c50 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
10c60 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
10c70 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
10c80 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
10c90 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
10ca0 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
10cb0 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
10cc0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
10cd0 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
10ce0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
10cf0 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
10d00 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10d10 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
10d20 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
10d30 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
10d40 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
10d50 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
10d60 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
10d70 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10d80 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
10d90 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
10da0 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
10db0 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
10dc0 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
10dd0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
10de0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10df0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
10e00 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
10e10 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
10e20 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
10e30 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
10e40 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
10e50 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
10e60 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
10e70 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
10e80 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
10e90 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
10ea0 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
10eb0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
10ec0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
10ed0 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
10ee0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
10ef0 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
10f00 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
10f10 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
10f20 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
10f30 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
10f40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
10f50 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10f60 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
10f70 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
10f80 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
10f90 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
10fa0 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
10fb0 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
10fc0 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49  failure..*/.SQLI
10fd0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
10fe0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
10ff0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
11000 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
11010 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  down(void);.SQLI
11020 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
11030 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
11040 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
11050 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
11060 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
11070 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
11080 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
11090 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65  ibrary.**.** The
110a0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
110b0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
110c0 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
110d0 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
110e0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
110f0 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
11100 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
11110 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
11120 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
11130 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
11140 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
11150 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
11160 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
11170 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
11180 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
11190 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
111a0 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
111b0 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
111c0 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
111d0 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
111e0 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
111f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
11200 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
11210 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
11220 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
11230 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
11240 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
11250 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
11260 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
11270 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
11280 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
11290 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
112a0 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
112b0 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
112c0 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
112d0 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
112e0 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
112f0 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
11300 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
11310 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
11320 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
11330 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
11340 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
11350 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
11360 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
11370 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
11380 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
11390 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
113a0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
113b0 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
113c0 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
113d0 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
113e0 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
113f0 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
11400 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
11410 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
11420 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
11430 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
11440 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
11450 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
11460 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11470 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
11480 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
11490 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  er.** [SQLITE_CO
114a0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
114b0 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  D | configuratio
114c0 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
114d0 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
114e0 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
114f0 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
11500 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
11510 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
11520 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
11530 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45  g on the [SQLITE
11540 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
11550 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61  READ | configura
11560 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20  tion option].** 
11570 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
11580 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  ument..**.** ^Wh
11590 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69  en a configurati
115a0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  on option is set
115b0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
115c0 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  () returns [SQLI
115d0 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74  TE_OK]..** ^If t
115e0 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b  he option is unk
115f0 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69  nown or SQLite i
11600 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20  s unable to set 
11610 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68  the option.** th
11620 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
11630 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
11640 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ro [error code].
11650 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
11660 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
11670 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
11680 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
11690 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
116a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a   connections.**.
116b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
116c0 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
116d0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
116e0 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
116f0 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
11700 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
11710 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
11720 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
11730 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
11740 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
11750 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
11760 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
11770 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
11780 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11790 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
117a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
117b0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
117c0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
117d0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
117e0 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
117f0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
11800 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
11810 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
11820 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
11830 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
11840 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
11850 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
11860 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11870 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
11880 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
11890 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
118a0 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
118b0 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
118c0 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
118d0 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
118e0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
118f0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
11900 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
11910 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
11920 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
11930 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  sful..*/.SQLITE_
11940 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
11950 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
11960 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
11970 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11980 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
11990 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
119a0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
119b0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
119c0 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
119d0 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
119e0 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
119f0 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
11a00 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
11a10 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
11a20 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
11a30 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
11a40 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
11a50 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
11a60 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
11a70 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
11a80 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
11a90 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
11aa0 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
11ab0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
11ac0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
11ad0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
11ae0 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
11af0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
11b00 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
11b10 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
11b20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
11b30 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
11b40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
11b50 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
11b60 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
11b70 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
11b80 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
11b90 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
11ba0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
11bb0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
11bc0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
11bd0 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
11be0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
11bf0 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
11c00 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
11c10 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
11c20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
11c30 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
11c40 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
11c50 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
11c60 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
11c70 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
11c80 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
11c90 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
11ca0 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
11cb0 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
11cc0 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
11cd0 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
11ce0 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
11cf0 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
11d00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
11d10 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
11d20 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
11d30 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
11d40 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
11d50 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
11d60 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
11d70 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
11d80 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
11d90 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
11da0 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
11db0 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
11dc0 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
11dd0 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
11de0 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
11df0 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
11e00 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
11e10 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78 46 72 65  xMalloc and xFre
11e20 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
11e30 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
11e40 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
11e50 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  e() functions fr
11e60 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
11e70 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68  C library..** Th
11e80 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f  e xRealloc metho
11e90 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  d must work like
11ea0 20 72 65 61 6c 6c 6f 63 28 29 20 66 72 6f 6d 20   realloc() from 
11eb0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
11ec0 69 62 72 61 72 79 0a 2a 2a 20 77 69 74 68 20 74  ibrary.** with t
11ed0 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74 68 61  he exception tha
11ee0 74 20 69 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t if the second 
11ef0 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 52 65 61  argument to xRea
11f00 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  lloc is zero,.**
11f10 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73 74 20 62   xRealloc must b
11f20 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d  e a no-op - it m
11f30 75 73 74 20 6e 6f 74 20 70 65 72 66 6f 72 6d 20  ust not perform 
11f40 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  any allocation o
11f50 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 69 6f  r.** deallocatio
11f60 6e 2e 20 20 5e 53 51 4c 69 74 65 20 67 75 61 72  n.  ^SQLite guar
11f70 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
11f80 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
11f90 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
11fa0 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
11fb0 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
11fc0 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
11fd0 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f  undup..** And so
11fe0 20 69 6e 20 63 61 73 65 73 20 77 68 65 72 65 20   in cases where 
11ff0 78 52 6f 75 6e 64 75 70 20 61 6c 77 61 79 73 20  xRoundup always 
12000 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69  returns a positi
12010 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78 52  ve number,.** xR
12020 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65 72 66 6f  ealloc can perfo
12030 72 6d 20 65 78 61 63 74 6c 79 20 61 73 20 74 68  rm exactly as th
12040 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61  e standard libra
12050 72 79 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ry realloc() and
12060 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20 69 6e 20  .** still be in 
12070 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69 74 68 20  compliance with 
12080 74 68 69 73 20 73 70 65 63 69 66 69 63 61 74 69  this specificati
12090 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  on..**.** xSize 
120a0 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
120b0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
120c0 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
120d0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
120e0 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
120f0 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
12100 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
12110 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
12120 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
12130 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
12140 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
12150 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
12160 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
12170 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
12180 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
12190 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
121a0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
121b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
121c0 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
121d0 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
121e0 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
121f0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
12200 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
12210 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
12220 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
12230 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
12240 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
12250 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
12260 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
12270 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
12280 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
12290 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
122a0 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
122b0 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
122c0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
122d0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
122e0 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
122f0 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
12300 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
12310 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
12320 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
12330 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
12340 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
12350 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
12360 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
12370 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
12380 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20  llocator.  (For 
12390 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
123a0 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
123b0 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
123c0 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
123d0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
123e0 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
123f0 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
12400 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
12410 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
12420 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
12430 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
12440 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
12450 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
12460 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
12470 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
12480 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
12490 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
124a0 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
124b0 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
124c0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
124d0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
124e0 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
124f0 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
12500 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
12510 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
12520 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
12530 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
12540 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
12550 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
12560 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
12570 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
12580 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
12590 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
125a0 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
125b0 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
125c0 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
125d0 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
125e0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
125f0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
12600 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
12610 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
12620 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
12630 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
12640 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
12650 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
12660 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
12670 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
12680 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
12690 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
126a0 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
126b0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
126c0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
126d0 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
126e0 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
126f0 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
12700 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
12710 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
12720 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
12730 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
12740 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
12750 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
12760 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
12770 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
12780 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
12790 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
127a0 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
127b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
127c0 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
127d0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
127e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
127f0 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
12800 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
12810 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
12820 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
12830 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
12840 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
12850 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
12860 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
12870 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
12880 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
12890 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
128a0 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
128b0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
128c0 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
128d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
128e0 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
128f0 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
12900 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
12910 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
12920 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
12930 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
12940 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
12950 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
12960 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
12970 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
12980 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12990 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
129a0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
129b0 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
129c0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
129d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
129e0 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
129f0 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
12a00 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
12a10 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
12a20 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
12a30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12a40 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
12a50 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
12a60 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
12a70 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
12a80 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
12a90 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
12aa0 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
12ab0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
12ac0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
12ad0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12ae0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
12af0 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
12b00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
12b10 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
12b20 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
12b30 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
12b40 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
12b50 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
12b60 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
12b70 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
12b80 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
12b90 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
12ba0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
12bb0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
12bc0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
12bd0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
12be0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
12bf0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
12c00 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
12c10 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
12c20 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
12c30 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
12c40 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
12c50 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
12c60 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
12c70 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
12c80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
12c90 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
12ca0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
12cb0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
12cc0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
12cd0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
12ce0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
12cf0 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
12d00 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
12d10 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
12d20 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
12d30 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
12d40 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
12d50 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
12d60 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
12d70 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
12d80 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
12d90 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
12da0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12db0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
12dc0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
12dd0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
12de0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
12df0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
12e00 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
12e10 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12e20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
12e30 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
12e40 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
12e50 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
12e60 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
12e70 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
12e80 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
12e90 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
12ea0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
12eb0 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
12ec0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
12ed0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
12ee0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
12ef0 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
12f00 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
12f10 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
12f20 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
12f30 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
12f40 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12f50 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
12f60 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
12f70 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
12f80 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
12f90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12fa0 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
12fb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
12fc0 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
12fd0 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
12fe0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
12ff0 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
13000 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
13010 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
13020 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
13030 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
13040 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
13050 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
13060 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
13070 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
13080 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
13090 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
130a0 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
130b0 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
130c0 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
130d0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
130e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
130f0 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
13100 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
13110 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
13120 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13130 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
13140 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
13150 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
13160 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
13170 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
13180 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
13190 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
131a0 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
131b0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
131c0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
131d0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
131e0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
131f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
13200 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
13210 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
13220 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
13230 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
13240 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
13250 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
13260 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
13270 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
13280 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
13290 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
132a0 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
132b0 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
132c0 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
132d0 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
132e0 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
132f0 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
13300 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
13310 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13320 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
13330 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
13340 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
13350 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
13360 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
13370 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13380 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
13390 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
133a0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
133b0 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
133c0 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
133d0 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
133e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
133f0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
13400 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
13410 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
13420 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
13430 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
13440 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13450 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
13460 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
13470 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
13480 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
13490 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
134a0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
134b0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
134c0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
134d0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
134e0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
134f0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
13500 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
13510 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
13520 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
13530 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
13540 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
13550 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
13560 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
13570 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
13580 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
13590 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
135a0 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
135b0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
135c0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
135d0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
135e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
135f0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13600 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13610 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
13620 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
13630 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
13640 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
13650 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
13660 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
13670 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
13680 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
13690 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
136a0 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
136b0 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
136c0 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
136d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
136e0 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
136f0 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
13700 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
13710 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
13720 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
13730 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
13740 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
13750 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
13760 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
13770 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
13780 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
13790 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
137a0 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
137b0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
137c0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
137d0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
137e0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
137f0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
13800 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13810 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
13820 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
13830 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
13840 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
13850 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
13860 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
13870 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
13880 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
13890 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
138a0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
138b0 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
138c0 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
138d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
138e0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
138f0 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
13900 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
13910 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
13920 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
13930 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
13940 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
13950 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
13960 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
13970 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  S</dt>.** <dd> ^
13980 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
13990 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
139a0 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69  t of type int, i
139b0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
139c0 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  .** boolean, whi
139d0 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
139e0 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
139f0 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20  ction of memory 
13a00 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73  allocation .** s
13a10 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65  tatistics. ^(Whe
13a20 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
13a30 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
13a40 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  re disabled, the
13a50 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   .** following S
13a60 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
13a70 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
13a80 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
13a90 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
13aa0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
13ab0 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
13ac0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
13ad0 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
13ae0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
13af0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
13b00 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
13b10 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
13b20 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
13b30 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
13b40 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
13b50 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
13b60 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
13b70 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
13b80 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
13b90 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
13ba0 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
13bb0 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
13bc0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
13bd0 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
13be0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
13bf0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
13c00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
13c10 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
13c20 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
13c30 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
13c40 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
13c50 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
13c60 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
13c70 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
13c80 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
13c90 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
13ca0 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
13cb0 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
13cc0 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
13cd0 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
13ce0 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
13cf0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
13d00 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
13d10 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
13d20 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
13d30 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
13d40 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13d50 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
13d60 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
13d70 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
13d80 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
13d90 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
13da0 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
13db0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
13dc0 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
13dd0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
13de0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
13df0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
13e00 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
13e10 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
13e20 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
13e30 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
13e40 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
13e50 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
13e60 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
13e70 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
13e80 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
13e90 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
13ea0 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
13eb0 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
13ec0 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
13ed0 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
13ee0 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
13ef0 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
13f00 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
13f10 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
13f20 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
13f30 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
13f40 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
13f50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13f60 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
13f70 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
13f80 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
13f90 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
13fa0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
13fb0 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
13fc0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
13fd0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
13fe0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
13ff0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
14000 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64  use for.** the d
14010 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
14020 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
14030 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ult page cache i
14040 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a  mplemenation.  .
14050 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
14060 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
14070 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
14080 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
14090 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
140a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
140b0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
140c0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
140d0 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a  _PCACHE option..
140e0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
140f0 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
14100 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70  this option: A p
14110 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65  ointer to 8-byte
14120 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f   aligned.** memo
14130 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
14140 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
14150 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
14160 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
14170 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
14180 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
14190 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
141a0 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
141b0 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
141c0 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
141d0 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29  n 512 and 32768)
141e0 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65   plus a little e
141f0 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a  xtra for each.**
14200 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e   page header.  ^
14210 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20  The page header 
14220 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30  size is 20 to 40
14230 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67   bytes depending
14240 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20   on.** the host 
14250 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e  architecture.  ^
14260 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
14270 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
14280 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
14290 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69   to make sz a li
142a0 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20  ttle too large. 
142b0 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
142c0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
142d0 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
142e0 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
142f0 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
14300 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
14310 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d  e will use the m
14320 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62  emory provided b
14330 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
14340 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20  ment to satisfy 
14350 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65  its.** memory ne
14360 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73  eds for the firs
14370 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69  t N pages that i
14380 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e  t adds to cache.
14390 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c    ^If additional
143a0 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
143b0 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
143c0 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
143d0 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
143e0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
143f0 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
14400 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14410 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
14420 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
14430 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  ce..** The point
14440 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
14450 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a  argument must.**
14460 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
14470 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
14480 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
14490 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
144a0 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e  te.** will be un
144b0 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
144c0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
144d0 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
144e0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
144f0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
14500 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
14510 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
14520 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f  e will use.** fo
14530 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
14540 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
14550 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79  cation needs bey
14560 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
14570 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51  ed.** for by [SQ
14580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
14590 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  TCH] and [SQLITE
145a0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
145b0 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  E]..** There are
145c0 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
145d0 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  : An 8-byte alig
145e0 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
145f0 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
14600 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
14610 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
14620 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
14630 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
14640 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
14650 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
14660 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
14670 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
14680 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
14690 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
146a0 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
146b0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
146c0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
146d0 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
146e0 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
146f0 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
14700 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
14710 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
14720 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
14730 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
14740 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20  NULL and either 
14750 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
14760 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53  EMSYS3] or.** [S
14770 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
14780 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65  SYS5] are define
14790 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  d, then the alte
147a0 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
147b0 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
147c0 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
147d0 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
147e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
147f0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
14800 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
14810 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
14820 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
14830 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
14840 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
14850 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
14860 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
14870 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a  l be undefined..
14880 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61  ** The minimum a
14890 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69  llocation size i
148a0 73 20 63 61 70 70 65 64 20 61 74 20 32 5e 31 32  s capped at 2^12
148b0 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c  . Reasonable val
148c0 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ues.** for the m
148d0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
148e0 6e 20 73 69 7a 65 20 61 72 65 20 32 5e 35 20 74  n size are 2^5 t
148f0 68 72 6f 75 67 68 20 32 5e 38 2e 3c 2f 64 64 3e  hrough 2^8.</dd>
14900 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
14910 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
14920 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
14930 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
14940 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
14950 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
14960 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
14970 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
14980 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14990 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
149a0 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
149b0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
149c0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
149d0 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
149e0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
149f0 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
14a00 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
14a10 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
14a20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
14a30 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
14a40 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
14a50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
14a60 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
14a70 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
14a80 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
14a90 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
14aa0 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
14ab0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
14ac0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
14ad0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
14ae0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
14af0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14b00 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
14b10 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
14b20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
14b30 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
14b40 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
14b50 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
14b60 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
14b70 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
14b80 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
14b90 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
14ba0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
14bb0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
14bc0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
14bd0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14be0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
14bf0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
14c00 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14c10 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
14c20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
14c30 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
14c40 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
14c50 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
14c60 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
14c70 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14c80 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
14c90 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
14ca0 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
14cb0 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
14cc0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
14cd0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
14ce0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
14cf0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
14d00 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
14d10 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
14d20 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
14d30 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
14d40 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
14d50 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
14d60 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
14d70 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
14d80 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
14d90 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
14da0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14db0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
14dc0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
14dd0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
14de0 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
14df0 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
14e00 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
14e10 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
14e20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
14e30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14e40 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
14e50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14e60 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
14e70 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
14e80 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
14e90 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
14ea0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
14eb0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
14ec0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14ed0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
14ee0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
14ef0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
14f00 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
14f10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
14f20 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  or the lookaside
14f30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
14f40 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61  r on each.** [da
14f50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14f60 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  n].  The first a
14f70 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
14f80 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
14f90 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
14fa0 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
14fb0 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
14fc0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
14fd0 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
14fe0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14ff0 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f  ion.)^  ^(This o
15000 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
15010 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
15020 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
15030 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
15040 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
15050 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c  .** verb to [sql
15060 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
15070 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
15080 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
15090 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
150a0 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
150b0 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
150c0 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
150d0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
150e0 47 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  G_PCACHE</dt>.**
150f0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
15100 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15110 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
15120 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
15130 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33  o.** an [sqlite3
15140 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d  _pcache_methods]
15150 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
15160 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20  bject specifies 
15170 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
15180 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
15190 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
151a0 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69  tation.)^  ^SQLi
151b0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
151c0 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74  of the.** object
151d0 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72   and uses it for
151e0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
151f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c  ry allocations.<
15200 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
15210 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15220 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  PCACHE</dt>.** <
15230 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
15240 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15250 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
15260 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
15270 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  an.** [sqlite3_p
15280 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f  cache_methods] o
15290 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
152a0 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72  opies of the cur
152b0 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63  rent.** page cac
152c0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
152d0 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
152e0 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
152f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15300 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
15310 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
15320 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
15330 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
15340 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
15350 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
15360 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
15370 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
15380 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
15390 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
153a0 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
153b0 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
153c0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
153d0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
153e0 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
153f0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
15400 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
15410 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
15420 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
15430 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
15440 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
15450 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
15460 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
15470 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
15480 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
15490 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
154a0 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
154b0 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
154c0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
154d0 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
154e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
154f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
15500 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
15510 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
15520 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
15530 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
15540 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
15550 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
15560 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
15570 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
15580 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
15590 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
155a0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
155b0 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
155c0 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
155d0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
155e0 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
155f0 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
15600 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
15610 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
15620 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
15630 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
15640 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
15650 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
15660 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
15670 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
15680 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
15690 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
156a0 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
156b0 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
156c0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
156d0 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
156e0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
156f0 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
15700 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
15710 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
15720 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
15730 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
15740 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
15750 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
15760 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
15770 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
15780 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
15790 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
157a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
157b0 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
157c0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
157d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
157e0 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
157f0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
15800 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15810 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
15820 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
15830 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
15840 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15850 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
15860 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
15870 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
15880 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15890 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
158a0 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
158b0 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
158c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
158d0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
158e0 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
158f0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
15900 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15910 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
15920 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
15930 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
15940 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
15950 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15960 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
15970 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
15980 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15990 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
159a0 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
159b0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
159c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
159d0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
159e0 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
159f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
15a00 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
15a10 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
15a20 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
15a30 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
15a40 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
15a50 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15a60 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
15a70 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
15a80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15a90 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
15aa0 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65     14  /* sqlite
15ab0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15ac0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
15ad0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15ae0 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73  ACHE    15  /* s
15af0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
15b00 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
15b10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15b20 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
15b30 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
15b40 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
15b50 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
15b60 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
15b70 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
15b80 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
15b90 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
15ba0 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
15bb0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15bc0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
15bd0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
15be0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
15bf0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
15c00 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
15c10 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
15c20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
15c30 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
15c40 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
15c50 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
15c60 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
15c70 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15c80 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
15c90 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
15ca0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
15cb0 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
15cc0 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
15cd0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
15ce0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
15cf0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
15d00 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
15d10 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
15d20 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
15d30 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
15d40 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
15d50 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
15d60 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
15d70 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
15d80 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
15d90 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
15da0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
15db0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
15dc0 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
15dd0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
15de0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
15df0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
15e00 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
15e10 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
15e20 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
15e30 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
15e40 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
15e50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
15e60 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
15e70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
15e80 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
15e90 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
15ea0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
15eb0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
15ec0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
15ed0 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
15ee0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
15ef0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15f00 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
15f10 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
15f20 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
15f30 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
15f40 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
15f50 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
15f60 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
15f70 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
15f80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
15f90 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
15fa0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
15fb0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
15fc0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
15fd0 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
15fe0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
15ff0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
16000 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
16010 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
16020 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
16030 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
16040 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
16050 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
16060 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
16070 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
16080 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
16090 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
160a0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
160b0 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
160c0 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
160d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
160e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
160f0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
16100 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
16110 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
16120 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
16130 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
16140 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
16150 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
16160 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
16170 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
16180 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
16190 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
161a0 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
161b0 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
161c0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
161d0 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
161e0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
161f0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
16200 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
16210 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
16220 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
16230 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
16240 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
16250 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
16260 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
16270 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
16280 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
16290 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
162a0 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
162b0 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
162c0 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
162d0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
162e0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
162f0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
16300 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
16310 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
16320 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
16330 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
16340 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
16350 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
16360 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
16370 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
16380 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
16390 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
163a0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
163b0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
163c0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
163d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
163e0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
163f0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
16400 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
16410 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
16420 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
16430 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
16440 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
16450 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
16460 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
16470 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16480 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16490 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
164a0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
164b0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
164c0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
164d0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
164e0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
164f0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
16500 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
16510 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
16520 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
16530 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
16540 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
16550 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
16560 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
16570 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
16580 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
16590 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
165a0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
165b0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
165c0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
165d0 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
165e0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
165f0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
16600 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
16610 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
16620 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
16630 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
16640 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
16650 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
16660 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
16670 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
16680 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
16690 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
166a0 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
166b0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
166c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
166d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
166e0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
166f0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
16700 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
16710 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
16720 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
16730 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
16740 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
16750 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
16760 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
16770 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
16780 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
16790 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
167a0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
167b0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
167c0 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
167d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
167e0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
167f0 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20         1001  /* 
16800 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
16810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16820 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
16830 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f  FKEY     1002  /
16840 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
16850 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
16860 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
16870 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69  GGER  1003  /* i
16880 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
16890 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
168a0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
168b0 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
168c0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  odes.**.** ^The 
168d0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
168e0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
168f0 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
16900 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
16910 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
16920 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
16930 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
16940 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
16950 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
16960 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
16970 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
16980 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
16990 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
169a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
169b0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
169c0 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
169d0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
169e0 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
169f0 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
16a00 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
16a10 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
16a20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
16a30 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
16a40 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
16a50 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
16a60 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
16a70 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
16a80 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
16a90 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
16aa0 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
16ab0 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
16ac0 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
16ad0 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
16ae0 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
16af0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
16b00 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
16b10 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
16b20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
16b30 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
16b40 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
16b50 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
16b60 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
16b70 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
16b80 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
16b90 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
16ba0 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
16bb0 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
16bc0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
16bd0 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
16be0 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
16bf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
16c00 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
16c10 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20  gument.  ^If no 
16c20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
16c30 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  RT]s.** have eve
16c40 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
16c50 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  at database conn
16c60 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
16c70 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
16c80 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
16c90 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
16ca0 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
16cb0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
16cc0 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
16cd0 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  w is returned by
16ce0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73   this routine as
16cf0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
16d00 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gger is running.
16d10 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
16d20 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61   trigger termina
16d30 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  tes, the value r
16d40 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
16d50 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72  routine.** rever
16d60 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76  ts to the last v
16d70 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65  alue inserted be
16d80 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
16d90 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20   fired.)^.**.** 
16da0 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
16db0 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
16dc0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
16dd0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
16de0 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
16df0 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
16e00 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
16e10 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
16e20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
16e30 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
16e40 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
16e50 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
16e60 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
16e70 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
16e80 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
16e90 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
16ea0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
16eb0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
16ec0 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
16ed0 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
16ee0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
16ef0 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
16f00 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
16f10 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
16f20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
16f30 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
16f40 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
16f50 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
16f60 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
16f70 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
16f80 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
16f90 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
16fa0 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
16fb0 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
16fc0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
16fd0 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
16fe0 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
16ff0 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
17000 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
17010 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
17020 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
17030 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
17040 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
17050 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
17060 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
17070 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
17080 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
17090 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
170a0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
170b0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
170c0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
170d0 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
170e0 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
170f0 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
17100 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17110 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
17120 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
17130 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
17140 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
17150 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
17160 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
17170 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
17180 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
17190 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
171a0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
171b0 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
171c0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
171d0 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
171e0 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
171f0 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
17200 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
17210 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
17220 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
17230 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
17240 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
17250 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17260 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
17270 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
17280 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
17290 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
172a0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
172b0 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
172c0 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
172d0 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
172e0 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
172f0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
17300 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
17310 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
17320 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
17330 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
17340 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
17350 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28  parameter..** ^(
17360 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
17370 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
17380 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
17390 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
173a0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
173b0 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
173c0 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
173d0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
173e0 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
173f0 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b  rs or [foreign k
17400 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
17410 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55  not counted.)^ U
17420 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
17430 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
17440 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ()] function to 
17450 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e  find the total n
17460 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
17470 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  .** including ch
17480 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
17490 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72  triggers and for
174a0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
174b0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  ..**.** ^Changes
174c0 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
174d0 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79  are simulated by
174e0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
174f0 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20  trigger].** are 
17500 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e  not counted.  On
17510 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68  ly real table ch
17520 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
17530 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f  d..**.** ^(A "ro
17540 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
17550 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
17560 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
17570 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
17580 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
17590 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
175a0 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
175b0 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
175c0 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
175d0 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41  ffects of [REPLA
175e0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
175f0 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f  esolution,.** ro
17600 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72  llback, ABORT pr
17610 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20  ocessing, [DROP 
17620 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e  TABLE], or by an
17630 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
17640 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
17650 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
17660 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a   changes.)^.**.*
17670 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
17680 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
17690 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
176a0 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
176b0 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
176c0 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41  cript of a [CREA
176d0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
176e0 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20  gger]. .** Most 
176f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
17700 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
17710 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
17720 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
17730 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
17740 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
17750 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
17760 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
17770 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
17780 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
17790 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
177a0 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
177b0 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
177c0 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
177d0 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
177e0 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
177f0 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
17800 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71  .** ^Calling [sq
17810 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
17820 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
17830 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f  ] recursively do
17840 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65  es.** not create
17850 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63   a new trigger c
17860 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
17870 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
17880 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
17890 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
178a0 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
178b0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
178c0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
178d0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
178e0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
178f0 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
17900 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c  xt..**.** ^Thus,
17910 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
17920 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
17930 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
17940 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
17950 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
17960 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
17970 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
17980 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
17990 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
179a0 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
179b0 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74  vel.  ^(Within t
179c0 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
179d0 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
179e0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
179f0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
17a00 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
17a10 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
17a20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
17a30 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
17a40 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
17a50 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
17a60 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
17a70 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
17a80 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
17a90 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
17aa0 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
17ab0 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
17ac0 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
17ad0 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
17ae0 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
17af0 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
17b00 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a  context.)^.**.**
17b10 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
17b20 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
17b30 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
17b40 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
17b50 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
17b60 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
17b70 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
17b80 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
17b90 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
17ba0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
17bb0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
17bc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
17bd0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
17be0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
17bf0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
17c00 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
17c10 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
17c20 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
17c30 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
17c40 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
17c50 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
17c60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17c70 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
17c80 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
17c90 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
17ca0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
17cb0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
17cc0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
17cd0 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b  y [INSERT],.** [
17ce0 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
17cf0 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73  TE] statements s
17d00 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
17d10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
17d20 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28  as opened..** ^(
17d30 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  The count return
17d40 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
17d50 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  tal_changes() in
17d60 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
17d70 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b  es.** from all [
17d80 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
17d90 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
17da0 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d  ts and changes m
17db0 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69  ade by.** [forei
17dc0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e  gn key actions].
17dd0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
17de0 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
17df0 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
17e00 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
17e10 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  t [REPLACE] cons
17e20 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72  traints,.** do r
17e30 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
17e40 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72  T processing, or
17e50 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72   [DROP TABLE] pr
17e60 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a  ocessing.  The.*
17e70 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  * count does not
17e80 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66   include rows of
17e90 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65   views that fire
17ea0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
17eb0 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f  trigger],.** tho
17ec0 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45  ugh if the INSTE
17ed0 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61  AD OF trigger ma
17ee0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69  kes changes of i
17ef0 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68  ts own, those ch
17f00 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f  anges .** are co
17f10 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65  unted.)^.** ^The
17f20 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
17f30 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
17f40 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61  n counts the cha
17f50 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a  nges as soon as.
17f60 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
17f70 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
17f80 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
17f90 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
17fa0 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70  t handle.** is p
17fb0 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
17fc0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
17fd0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
17fe0 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
17ff0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
18000 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
18010 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
18020 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
18030 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
18040 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
18050 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
18060 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
18070 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
18080 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
18090 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
180a0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
180b0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
180c0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
180d0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
180e0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
180f0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
18100 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
18110 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
18120 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
18130 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
18140 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
18150 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
18160 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
18170 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
18180 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
18190 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
181a0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
181b0 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
181c0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
181d0 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
181e0 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
181f0 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
18200 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
18210 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
18220 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
18230 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
18240 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
18250 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
18260 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
18270 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
18280 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
18290 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
182a0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
182b0 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
182c0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
182d0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
182e0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
182f0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
18300 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
18310 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
18320 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
18330 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
18340 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
18350 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
18360 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
18370 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
18380 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
18390 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
183a0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
183b0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
183c0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
183d0 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
183e0 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
183f0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
18400 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
18410 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
18420 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
18430 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
18440 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
18450 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
18460 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
18470 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
18480 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
18490 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
184a0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
184b0 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
184c0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
184d0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
184e0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
184f0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
18500 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
18510 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
18520 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
18530 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
18540 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
18550 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
18560 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
18570 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18580 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
18590 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
185a0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
185b0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
185c0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
185d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
185e0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
185f0 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
18600 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
18610 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
18620 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
18630 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
18640 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
18650 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
18660 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
18670 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
18680 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
18690 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
186a0 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
186b0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
186c0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
186d0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
186e0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
186f0 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
18700 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
18710 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
18720 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
18730 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
18740 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
18750 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
18760 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
18770 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
18780 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
18790 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
187a0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
187b0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
187c0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
187d0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
187e0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
187f0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
18800 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
18810 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
18820 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
18830 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
18840 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
18850 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
18860 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
18870 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
18880 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53  ely happen..*/.S
18890 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
188a0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
188b0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
188c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
188d0 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
188e0 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
188f0 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
18900 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
18910 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
18920 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
18930 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
18940 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
18950 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
18960 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
18970 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
18980 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
18990 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
189a0 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
189b0 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
189c0 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
189d0 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
189e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
189f0 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
18a00 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
18a10 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
18a20 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
18a30 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
18a40 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
18a50 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
18a60 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
18a70 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
18a80 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
18a90 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
18aa0 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
18ab0 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
18ac0 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
18ad0 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
18ae0 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
18af0 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
18b00 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
18b10 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
18b20 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
18b30 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
18b40 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
18b50 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
18b60 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
18b70 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
18b80 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
18b90 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
18ba0 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
18bb0 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
18bc0 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
18bd0 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
18be0 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
18bf0 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
18c00 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
18c10 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
18c20 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
18c30 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
18c40 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
18c50 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
18c60 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
18c70 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
18c80 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
18c90 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
18ca0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
18cb0 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
18cc0 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
18cd0 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
18ce0 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
18cf0 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
18d00 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
18d10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
18d20 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
18d30 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
18d40 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
18d50 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
18d60 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
18d70 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
18d80 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
18d90 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
18da0 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
18db0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
18dc0 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
18dd0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
18de0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
18df0 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
18e00 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
18e10 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
18e20 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
18e30 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
18e40 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
18e50 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
18e60 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
18e70 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
18e80 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
18e90 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
18ea0 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
18eb0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
18ec0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
18ed0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
18ee0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
18ef0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
18f00 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  der..*/.SQLITE_A
18f10 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
18f20 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
18f30 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45  ar *sql);.SQLITE
18f40 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
18f50 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
18f60 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
18f70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
18f80 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
18f90 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
18fa0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
18fb0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
18fc0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
18fd0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
18fe0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
18ff0 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
19000 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
19010 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
19020 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
19030 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
19040 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
19050 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
19060 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
19070 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
19080 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
19090 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
190a0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
190b0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
190c0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
190d0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
190e0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
190f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
19100 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
19110 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
19120 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
19130 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
19140 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
19150 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
19160 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
19170 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
19180 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
19190 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
191a0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
191b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
191c0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
191d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
191e0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
191f0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
19200 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
19210 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
19220 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
19230 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
19240 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
19250 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
19260 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
19270 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
19280 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
19290 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
192a0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
192b0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
192c0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
192d0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
192e0 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
192f0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
19300 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
19310 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
19320 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
19330 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
19340 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
19350 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
19360 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
19370 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
19380 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
19390 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
193a0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
193b0 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
193c0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
193d0 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
193e0 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
193f0 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
19400 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
19410 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
19420 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
19430 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
19440 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
19450 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
19460 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
19470 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
19480 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
19490 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
194a0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
194b0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
194c0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
194d0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
194e0 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
194f0 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
19500 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
19510 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
19520 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
19530 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
19540 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
19550 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
19560 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
19570 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
19580 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
19590 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
195a0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
195b0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
195c0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
195d0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
195e0 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
195f0 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
19600 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
19610 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
19620 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
19630 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
19640 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
19650 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
19660 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
19670 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
19680 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
19690 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
196a0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
196b0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
196c0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
196d0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
196e0 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
196f0 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
19700 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
19710 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
19720 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
19730 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
19740 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
19750 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
19760 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
19770 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
19780 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
19790 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
197a0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
197b0 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
197c0 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
197d0 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
197e0 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
197f0 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
19800 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
19810 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
19820 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
19830 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
19840 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
19850 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
19860 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
19870 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
19880 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
19890 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
198a0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
198b0 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
198c0 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
198d0 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
198e0 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
198f0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
19900 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
19910 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
19920 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
19930 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
19940 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
19950 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
19960 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
19970 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
19980 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
19990 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
199a0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
199b0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
199c0 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
199d0 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
199e0 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
199f0 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
19a00 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
19a10 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
19a20 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
19a30 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
19a40 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
19a50 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
19a60 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
19a70 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
19a80 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
19a90 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
19aa0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
19ab0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
19ac0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
19ad0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
19ae0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
19af0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
19b00 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
19b10 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
19b20 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
19b30 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
19b40 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
19b50 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
19b60 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
19b70 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
19b80 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
19b90 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
19ba0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
19bb0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
19bc0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
19bd0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
19be0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
19bf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19c00 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
19c10 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19c20 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
19c30 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
19c40 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
19c50 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
19c60 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
19c70 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
19c80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19c90 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
19ca0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
19cb0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
19cc0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53  sy handler..*/.S
19cd0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
19ce0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
19cf0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
19d00 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
19d10 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
19d20 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
19d30 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a  usy Timeout.**.*
19d40 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
19d50 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
19d60 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
19d70 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
19d80 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
19d90 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
19da0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
19db0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
19dc0 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
19dd0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
19de0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
19df0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
19e00 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
19e10 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
19e20 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
19e30 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
19e40 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
19e50 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
19e60 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
19e70 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
19e80 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
19e90 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
19ea0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
19eb0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
19ec0 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
19ed0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
19ee0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
19ef0 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
19f00 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
19f10 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
19f20 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
19f30 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
19f40 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
19f50 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
19f60 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
19f70 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
19f80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
19f90 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  ny any given mom
19fa0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
19fb0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
19fc0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
19fd0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
19fe0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
19ff0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
1a000 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
1a010 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
1a020 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
1a030 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  red.)^.*/.SQLITE
1a040 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1a050 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
1a060 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
1a070 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a080 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
1a090 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
1a0a0 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
1a0b0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
1a0c0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1a0d0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
1a0e0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1a0f0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
1a100 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
1a110 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
1a120 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
1a130 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
1a140 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
1a150 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
1a160 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
1a170 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
1a180 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1a190 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
1a1a0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
1a1b0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
1a1c0 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
1a1d0 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
1a1e0 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
1a1f0 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
1a200 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
1a210 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
1a220 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
1a230 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
1a240 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
1a250 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1a260 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
1a270 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
1a280 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
1a290 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
1a2a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1a2b0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
1a2c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1a2d0 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
1a2e0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
1a2f0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
1a300 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
1a310 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1a320 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
1a330 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
1a340 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
1a350 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1a360 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1a370 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1a380 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1a390 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1a3a0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1a3b0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1a3c0 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1a3d0 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1a3e0 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1a3f0 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1a400 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1a410 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1a420 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1a430 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1a440 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1a450 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1a460 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1a470 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1a480 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1a490 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1a4a0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1a4b0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1a4c0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1a4d0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1a4e0 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1a4f0 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1a500 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1a510 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1a520 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1a530 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1a540 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1a550 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1a560 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1a570 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1a580 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1a590 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1a5a0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1a5b0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1a5c0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1a5d0 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1a5e0 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1a5f0 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1a600 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1a610 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1a620 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1a630 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1a640 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1a650 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1a660 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1a670 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1a680 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1a690 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1a6a0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1a6b0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1a6c0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1a6d0 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1a6e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1a6f0 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1a700 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1a710 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1a720 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1a730 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1a740 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1a750 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
1a760 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1a770 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1a780 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1a790 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1a7a0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a7b0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1a7c0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a7d0 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1a7e0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a7f0 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1a800 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a810 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1a820 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1a830 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1a840 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1a850 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1a860 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1a870 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1a880 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1a890 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a8a0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1a8b0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1a8c0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1a8d0 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1a8e0 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1a8f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1a900 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1a910 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1a920 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1a930 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1a940 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1a950 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1a960 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1a970 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1a980 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1a990 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1a9a0 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1a9b0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1a9c0 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1a9d0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1a9e0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1a9f0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1aa00 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1aa10 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1aa20 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1aa30 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1aa40 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1aa50 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1aa60 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1aa70 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1aa80 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1aa90 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1aaa0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1aab0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1aac0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1aad0 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1aae0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1aaf0 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1ab00 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1ab10 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1ab20 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1ab30 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1ab40 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1ab50 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1ab60 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1ab70 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1ab80 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1ab90 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1aba0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1abb0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1abc0 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1abd0 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1abe0 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1abf0 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1ac00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1ac10 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1ac20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1ac30 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1ac40 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1ac50 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1ac60 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1ac70 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1ac80 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1ac90 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1aca0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1acb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1acc0 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1acd0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1ace0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1acf0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
1ad00 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1ad10 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1ad20 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1ad30 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1ad40 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1ad50 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1ad60 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1ad70 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1ad80 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1ad90 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1ada0 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1adb0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1adc0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1add0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1ade0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1adf0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1ae00 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1ae10 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1ae20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1ae30 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1ae40 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1ae50 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
1ae60 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  I void sqlite3_f
1ae70 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1ae80 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1ae90 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1aea0 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1aeb0 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1aec0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1aed0 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1aee0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1aef0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1af00 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1af10 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1af20 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
1af30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1af40 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1af50 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1af60 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1af70 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1af80 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1af90 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1afa0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1afb0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1afc0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1afd0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1afe0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1aff0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1b000 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1b010 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1b020 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1b030 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1b040 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1b050 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1b060 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1b070 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1b080 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1b090 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1b0a0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1b0b0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1b0c0 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1b0d0 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1b0e0 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1b0f0 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1b100 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1b110 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1b120 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1b130 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1b140 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1b150 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1b160 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1b170 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1b180 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1b190 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1b1a0 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1b1b0 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1b1c0 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1b1d0 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1b1e0 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1b1f0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1b200 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1b210 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1b220 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1b230 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1b240 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1b250 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1b260 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1b270 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1b280 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1b290 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1b2a0 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1b2b0 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1b2c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1b2d0 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1b2e0 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1b2f0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1b300 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1b310 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1b320 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1b330 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1b340 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1b350 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1b360 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1b370 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1b380 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1b390 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1b3a0 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1b3b0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1b3c0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1b3d0 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1b3e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1b3f0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1b400 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1b410 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1b420 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1b430 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1b440 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1b450 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1b460 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1b470 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1b480 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1b490 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1b4a0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1b4b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b4c0 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1b4d0 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1b4e0 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1b4f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1b500 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1b510 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1b520 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1b530 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1b540 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1b550 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1b560 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1b570 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1b580 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1b590 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1b5a0 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1b5b0 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1b5c0 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1b5d0 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
1b5e0 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1b5f0 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1b600 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1b610 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1b620 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74  titutes a null-t
1b630 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1b640 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
1b650 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
1b660 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
1b670 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
1b680 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
1b690 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
1b6a0 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
1b6b0 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20   literal.)^  By 
1b6c0 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
1b6d0 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
1b6e0 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
1b6f0 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
1b700 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
1b710 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
1b720 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
1b730 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
1b740 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
1b750 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
1b760 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
1b770 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1b780 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1b790 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
1b7a0 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
1b7b0 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
1b7c0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1b7d0 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
1b7e0 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
1b7f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1b800 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1b810 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1b820 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1b830 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1b840 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1b850 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
1b860 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
1b870 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1b880 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1b890 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1b8a0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1b8b0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1b8c0 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
1b8d0 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
1b8e0 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
1b8f0 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
1b900 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
1b910 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
1b920 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
1b930 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1b940 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1b950 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1b960 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1b970 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
1b980 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
1b990 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1b9a0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
1b9b0 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
1b9c0 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
1b9d0 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
1b9e0 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
1b9f0 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
1ba00 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
1ba10 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1ba20 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1ba30 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1ba40 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1ba50 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
1ba60 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1ba70 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
1ba80 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
1ba90 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
1baa0 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
1bab0 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
1bac0 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
1bad0 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
1bae0 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
1baf0 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
1bb00 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ral..**.** ^(The
1bb10 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
1bb20 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
1bb30 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
1bb40 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
1bb50 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
1bb60 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
1bb70 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
1bb80 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
1bb90 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
1bba0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
1bbb0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
1bbc0 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
1bbd0 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
1bbe0 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
1bbf0 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53  le quotes).)^  S
1bc00 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
1bc10 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
1bc20 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1bc30 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1bc40 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1bc50 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1bc60 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1bc70 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
1bc80 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1bc90 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1bca0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1bcb0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1bcc0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1bcd0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
1bce0 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
1bcf0 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
1bd00 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1bd10 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
1bd20 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
1bd30 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
1bd40 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1bd50 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  r..**.** ^(The "
1bd60 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
1bd70 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1bd80 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
1bd90 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
1bda0 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
1bdb0 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
1bdc0 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
1bdd0 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
1bde0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1bdf0 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
1be00 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1be10 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
1be20 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
1be30 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1be40 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  ar*,...);.SQLITE
1be50 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1be60 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1be70 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1be80 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1be90 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
1bea0 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1beb0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1bec0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1bed0 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
1bee0 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1bef0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1bf00 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
1bf10 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1bf20 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
1bf30 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
1bf40 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
1bf50 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
1bf60 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
1bf70 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
1bf80 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1bf90 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
1bfa0 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
1bfb0 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
1bfc0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
1bfd0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
1bfe0 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
1bff0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1c000 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
1c010 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
1c020 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1c030 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
1c040 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
1c050 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c060 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1c070 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1c080 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
1c090 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
1c0a0 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
1c0b0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
1c0c0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
1c0d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c0e0 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
1c0f0 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
1c100 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
1c110 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
1c120 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
1c130 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
1c140 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
1c150 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1c160 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
1c170 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c180 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
1c190 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1c1a0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
1c1b0 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
1c1c0 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
1c1d0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
1c1e0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1c1f0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1c200 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
1c210 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
1c220 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
1c230 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
1c240 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
1c250 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
1c260 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
1c270 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1c280 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
1c290 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
1c2a0 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
1c2b0 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
1c2c0 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
1c2d0 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
1c2e0 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
1c2f0 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
1c300 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
1c310 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
1c320 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
1c330 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
1c340 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1c350 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
1c360 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
1c370 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
1c380 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
1c390 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
1c3a0 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
1c3b0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
1c3c0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1c3d0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1c3e0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
1c3f0 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
1c400 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
1c410 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c420 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1c430 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  loc()..**.** ^(T
1c440 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1c450 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  oc() interface a
1c460 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
1c470 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
1c480 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1c490 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
1c4a0 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69  bytes, where N i
1c4b0 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20  s the.** second 
1c4c0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
1c4d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1c4e0 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20  n to be resized 
1c4f0 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
1c500 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49  parameter.)^ ^ I
1c510 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
1c520 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1c530 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
1c540 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1c550 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
1c560 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
1c570 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
1c580 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
1c590 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
1c5a0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1c5b0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1c5c0 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  c()..** ^If the 
1c5d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1c5e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1c5f0 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
1c600 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
1c610 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1c620 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
1c630 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
1c640 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29   sqlite3_free(P)
1c650 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20   where P is the 
1c660 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1c670 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1c680 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  oc()..** ^sqlite
1c690 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
1c6a0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1c6b0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1c6c0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1c6d0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1c6e0 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
1c6f0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1c700 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
1c710 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1c720 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1c730 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1c740 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1c750 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1c760 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1c770 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1c780 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1c790 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1c7a0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1c7b0 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70  lloc() and the p
1c7c0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1c7d0 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  is freed..** ^If
1c7e0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c7f0 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  () returns NULL,
1c800 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20   then the prior 
1c810 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
1c820 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
1c830 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
1c840 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1c850 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73  3_malloc() and s
1c860 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c870 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
1c880 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
1c890 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
1c8a0 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a  dary, or to a.**
1c8b0 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   4 byte boundary
1c8c0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1c8d0 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d  4_BYTE_ALIGNED_M
1c8e0 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74  ALLOC] compile-t
1c8f0 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73  ime.** option is
1c900 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20   used..**.** In 
1c910 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1c920 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
1c930 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
1c940 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
1c950 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
1c960 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
1c970 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
1c980 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
1c990 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1c9a0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1c9b0 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
1c9c0 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
1c9d0 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
1c9e0 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
1c9f0 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
1ca00 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
1ca10 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
1ca20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  The Windows OS i
1ca30 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
1ca40 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74  alls.** the syst
1ca50 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1ca60 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1ca70 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1ca80 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1ca90 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1caa0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1cab0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1cac0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1cad0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1cae0 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1caf0 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1cb00 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1cb10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1cb20 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74  rrors are detect
1cb30 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
1cb40 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  are reported bac
1cb50 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
1cb60 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
1cb70 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
1cb80 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1cb90 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
1cba0 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
1cbb0 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
1cbc0 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
1cbd0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1cbe0 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
1cbf0 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
1cc00 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
1cc10 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
1cc20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1cc30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1cc40 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1cc50 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
1cc60 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
1cc70 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
1cc80 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1cc90 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
1cca0 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
1ccb0 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
1ccc0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
1ccd0 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
1cce0 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
1ccf0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1cd00 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1cd10 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  loc()]..*/.SQLIT
1cd20 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
1cd30 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1cd40 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1cd50 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1cd60 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53  c(void*, int);.S
1cd70 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1cd80 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
1cd90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1cda0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1cdb0 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
1cdc0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
1cdd0 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
1cde0 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
1cdf0 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
1ce00 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
1ce10 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
1ce20 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
1ce30 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
1ce40 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1ce50 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
1ce60 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
1ce70 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1ce80 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
1ce90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
1cea0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1ceb0 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
1cec0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1ced0 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
1cee0 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
1cef0 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
1cf00 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
1cf10 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
1cf20 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1cf30 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
1cf40 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
1cf50 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
1cf60 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
1cf70 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
1cf80 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1cf90 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
1cfa0 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
1cfb0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1cfc0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1cfd0 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1cfe0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1cff0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
1d000 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
1d010 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
1d020 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
1d030 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
1d040 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1d050 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
1d060 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
1d070 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
1d080 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
1d090 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
1d0a0 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
1d0b0 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
1d0c0 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1d0d0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1d0e0 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
1d0f0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
1d100 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
1d110 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
1d120 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
1d130 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1d140 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1d150 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
1d160 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
1d170 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
1d180 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1d190 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
1d1a0 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
1d1b0 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
1d1c0 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
1d1d0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1d1e0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1d1f0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1d200 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  d);.SQLITE_API s
1d210 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1d220 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1d230 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
1d240 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
1d250 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
1d260 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
1d270 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
1d280 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
1d290 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
1d2a0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
1d2b0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
1d2c0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
1d2d0 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
1d2e0 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
1d2f0 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
1d300 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
1d310 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
1d320 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
1d330 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
1d340 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
1d350 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
1d360 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
1d370 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
1d380 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
1d390 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
1d3a0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1d3b0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
1d3c0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
1d3d0 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
1d3e0 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
1d3f0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
1d400 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
1d410 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
1d420 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
1d430 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fer P..**.** ^Th
1d440 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
1d450 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
1d460 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
1d470 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
1d480 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1d490 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
1d4a0 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
1d4b0 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
1d4c0 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
1d4d0 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
1d4e0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1d4f0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1d500 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75  t..** ^On all su
1d510 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
1d520 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
1d530 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1d540 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1d550 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1d560 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1d570 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1d580 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1d590 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54  method..*/.SQLIT
1d5a0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1d5b0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
1d5c0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
1d5d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d5e0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
1d5f0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
1d600 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
1d610 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
1d620 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  rs an authorizer
1d630 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
1d640 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1d650 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d660 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
1d670 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
1d680 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
1d690 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d6a0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
1d6b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
1d6c0 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
1d6d0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1d6e0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1d6f0 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
1d700 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d710 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1d720 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
1d730 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d740 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
1d750 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
1d760 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
1d770 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
1d780 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
1d790 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
1d7a0 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
1d7b0 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
1d7c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d7d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
1d7e0 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
1d7f0 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
1d800 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
1d810 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d820 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
1d830 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
1d840 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
1d850 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
1d860 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
1d870 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
1d880 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
1d890 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1d8a0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
1d8b0 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
1d8c0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1d8d0 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
1d8e0 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
1d8f0 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
1d900 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
1d910 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
1d920 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d930 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
1d940 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
1d950 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1d960 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
1d970 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
1d980 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
1d990 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d9a0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1d9b0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1d9c0 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
1d9d0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1d9e0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1d9f0 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
1da00 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1da10 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1da20 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
1da30 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
1da40 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
1da50 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
1da60 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1da70 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
1da80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1da90 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1daa0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1dab0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
1dac0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
1dad0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1dae0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
1daf0 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
1db00 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
1db10 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
1db20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1db30 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1db40 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
1db50 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
1db60 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
1db70 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
1db80 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
1db90 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
1dba0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
1dbb0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1dbc0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1dbd0 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1dbe0 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
1dbf0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
1dc00 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
1dc10 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1dc20 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
1dc30 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
1dc40 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
1dc50 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
1dc60 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1dc70 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
1dc80 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
1dc90 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
1dca0 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
1dcb0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
1dcc0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
1dcd0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1dce0 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
1dcf0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1dd00 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
1dd10 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
1dd20 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1dd30 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
1dd40 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
1dd50 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
1dd60 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
1dd70 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
1dd80 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
1dd90 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
1dda0 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
1ddb0 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
1ddc0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1ddd0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
1dde0 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
1ddf0 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
1de00 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
1de10 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
1de20 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
1de30 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
1de40 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1de50 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
1de60 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
1de70 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1de80 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
1de90 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
1dea0 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
1deb0 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
1dec0 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
1ded0 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
1dee0 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
1def0 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
1df00 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
1df10 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
1df20 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
1df30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1df40 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
1df50 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
1df60 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
1df70 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
1df80 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
1df90 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
1dfa0 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
1dfb0 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
1dfc0 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
1dfd0 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
1dfe0 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
1dff0 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
1e000 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
1e010 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
1e020 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
1e030 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
1e040 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
1e050 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
1e060 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
1e070 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
1e080 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
1e090 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
1e0a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1e0b0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
1e0c0 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
1e0d0 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
1e0e0 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
1e0f0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1e100 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
1e110 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
1e120 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
1e130 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
1e140 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
1e150 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1e160 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
1e170 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
1e180 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
1e190 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
1e1a0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
1e1b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1e1c0 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
1e1d0 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
1e1e0 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
1e1f0 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
1e200 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
1e210 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
1e220 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1e230 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
1e240 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
1e250 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
1e260 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
1e270 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
1e280 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
1e290 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
1e2a0 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
1e2b0 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
1e2c0 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
1e2d0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
1e2e0 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
1e2f0 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
1e300 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
1e310 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
1e320 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
1e330 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
1e340 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
1e350 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
1e360 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
1e370 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
1e380 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
1e390 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
1e3a0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1e3b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1e3c0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1e3d0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1e3e0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1e3f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1e400 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
1e410 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e420 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
1e430 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e440 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1e450 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1e460 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1e470 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1e480 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1e490 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1e4a0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1e4b0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
1e4c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e4d0 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
1e4e0 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
1e4f0 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
1e500 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
1e510 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
1e520 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
1e530 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
1e540 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
1e550 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
1e560 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
1e570 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1e580 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
1e590 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1e5a0 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
1e5b0 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
1e5c0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1e5d0 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
1e5e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e5f0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1e600 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
1e610 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e620 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
1e630 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
1e640 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
1e650 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
1e660 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
1e670 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
1e680 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
1e690 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
1e6a0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
1e6b0 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
1e6c0 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
1e6d0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
1e6e0 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
1e6f0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1e700 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
1e710 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54  change..*/.SQLIT
1e720 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1e730 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1e740 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1e750 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1e760 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1e770 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1e780 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1e790 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1e7a0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1e7b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1e7c0 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1e7d0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1e7e0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1e7f0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1e800 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
1e810 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
1e820 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
1e830 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
1e840 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
1e850 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
1e860 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
1e870 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
1e880 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
1e890 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
1e8a0 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
1e8b0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1e8c0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
1e8d0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1e8e0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1e8f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
1e900 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e910 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
1e920 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
1e930 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
1e940 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
1e950 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
1e960 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
1e970 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
1e980 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
1e990 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
1e9a0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1e9b0 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
1e9c0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1e9d0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1e9e0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
1e9f0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
1ea00 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
1ea10 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
1ea20 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
1ea30 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
1ea40 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
1ea50 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1ea60 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
1ea70 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1ea80 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
1ea90 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
1eaa0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
1eab0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
1eac0 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
1ead0 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
1eae0 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
1eaf0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
1eb00 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
1eb10 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
1eb20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
1eb30 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
1eb40 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
1eb50 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
1eb60 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
1eb70 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
1eb80 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
1eb90 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
1eba0 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
1ebb0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
1ebc0 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
1ebd0 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
1ebe0 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
1ebf0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1ec00 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
1ec10 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
1ec20 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
1ec30 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1ec40 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1ec50 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
1ec60 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
1ec70 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
1ec80 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
1ec90 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1eca0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1ecb0 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
1ecc0 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
1ecd0 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
1ece0 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
1ecf0 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
1ed00 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
1ed10 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
1ed20 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
1ed30 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
1ed40 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
1ed50 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
1ed60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ed70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ed80 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
1ed90 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
1eda0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
1edb0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1edc0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1edd0 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
1ede0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1edf0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ee00 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ee10 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1ee20 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ee30 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ee40 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ee50 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1ee60 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
1ee70 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1ee80 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1ee90 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1eea0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1eeb0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
1eec0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1eed0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1eee0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1eef0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1ef00 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
1ef10 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1ef20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1ef30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ef40 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1ef50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
1ef60 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1ef70 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1ef80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ef90 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
1efa0 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
1efb0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1efc0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1efd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1efe0 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
1eff0 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
1f000 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1f010 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f020 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f030 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
1f040 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
1f050 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1f060 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f070 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f080 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
1f090 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
1f0a0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1f0b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f0c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f0d0 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
1f0e0 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
1f0f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1f100 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f110 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f120 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
1f130 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
1f140 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1f150 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1f160 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f170 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
1f180 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
1f190 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f1a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f1b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f1c0 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
1f1d0 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
1f1e0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1f1f0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1f200 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f210 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1f220 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
1f230 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1f240 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f250 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f260 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
1f270 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
1f280 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1f290 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f2a0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1f2b0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
1f2c0 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
1f2d0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f2e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f2f0 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
1f300 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
1f310 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1f320 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f330 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f340 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
1f350 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
1f360 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
1f370 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
1f380 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
1f390 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
1f3a0 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
1f3b0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f3c0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1f3d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f3e0 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
1f3f0 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
1f400 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1f410 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f420 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f430 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
1f440 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
1f450 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1f460 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f470 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f480 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
1f490 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
1f4a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f4b0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1f4c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f4d0 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
1f4e0 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
1f4f0 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
1f500 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f510 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f520 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
1f530 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
1f540 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
1f550 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f560 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f570 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
1f580 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
1f590 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
1f5a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f5b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f5c0 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
1f5d0 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
1f5e0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
1f5f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f600 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1f610 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
1f620 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
1f630 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1f640 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f650 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1f660 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
1f670 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
1f680 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1f690 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1f6a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f6b0 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
1f6c0 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
1f6d0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1f6e0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1f6f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
1f700 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
1f710 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
1f720 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
1f730 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
1f740 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
1f750 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
1f760 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
1f770 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
1f780 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
1f790 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
1f7a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f7b0 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
1f7c0 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
1f7d0 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
1f7e0 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
1f7f0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1f800 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1f810 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
1f820 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
1f830 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
1f840 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
1f850 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
1f860 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
1f870 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1f880 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1f890 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1f8a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
1f8b0 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
1f8c0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
1f8d0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
1f8e0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
1f8f0 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
1f900 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
1f910 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
1f920 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
1f930 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
1f940 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
1f950 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
1f960 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
1f970 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
1f980 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
1f990 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
1f9a0 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
1f9b0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
1f9c0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
1f9d0 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
1f9e0 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
1f9f0 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
1fa00 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
1fa10 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
1fa20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
1fa30 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
1fa40 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
1fa50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
1fa60 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1fa70 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1fa80 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
1fa90 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
1faa0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
1fab0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
1fac0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1fad0 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
1fae0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
1faf0 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
1fb00 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
1fb10 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
1fb20 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
1fb30 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
1fb40 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
1fb50 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
1fb60 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
1fb70 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
1fb80 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
1fb90 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
1fba0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
1fbb0 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
1fbc0 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
1fbd0 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
1fbe0 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
1fbf0 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
1fc00 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
1fc10 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
1fc20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1fc30 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
1fc40 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
1fc50 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
1fc60 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
1fc70 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
1fc80 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
1fc90 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
1fca0 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
1fcb0 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
1fcc0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
1fcd0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1fce0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
1fcf0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
1fd00 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
1fd10 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
1fd20 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1fd30 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
1fd40 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
1fd50 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
1fd60 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
1fd70 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
1fd80 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
1fd90 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1fda0 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
1fdb0 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
1fdc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
1fdd0 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
1fde0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
1fdf0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1fe00 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
1fe10 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
1fe20 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
1fe30 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
1fe40 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
1fe50 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
1fe60 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
1fe70 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
1fe80 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
1fe90 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
1fea0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1feb0 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
1fec0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1fed0 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
1fee0 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
1fef0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
1ff00 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
1ff10 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
1ff20 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
1ff30 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
1ff40 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
1ff50 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
1ff60 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1ff70 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1ff80 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
1ff90 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
1ffa0 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
1ffb0 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
1ffc0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
1ffd0 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
1ffe0 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
1fff0 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
20000 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
20010 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  ack X..**.** ^On
20020 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
20030 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
20040 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
20050 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
20060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20070 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
20080 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
20090 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
200a0 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
200b0 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
200c0 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
200d0 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
200e0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
200f0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
20100 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
20110 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
20120 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
20130 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
20140 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
20150 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
20160 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
20170 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
20180 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
20190 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
201a0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
201b0 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
201c0 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
201d0 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
201e0 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
201f0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
20200 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
20210 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
20220 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
20230 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
20240 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
20250 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
20260 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
20270 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
20280 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20290 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
202a0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
202b0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
202c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
202d0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
202e0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
202f0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
20300 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f  h..**.*/.SQLITE_
20310 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
20320 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
20330 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
20340 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
20350 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
20360 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
20370 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
20380 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
20390 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
203a0 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
203b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68  database file wh
203c0 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65  ose name is give
203d0 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65  n by the.** file
203e0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
203f0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
20400 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
20410 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
20420 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
20430 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
20440 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
20450 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
20460 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
20470 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
20480 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
20490 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
204a0 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
204b0 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
204c0 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
204d0 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
204e0 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
204f0 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
20500 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
20510 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
20520 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
20530 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
20540 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
20550 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
20560 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
20570 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
20580 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
20590 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
205a0 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
205b0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
205c0 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
205d0 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
205e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
205f0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
20600 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
20610 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
20620 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
20630 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
20640 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
20650 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
20660 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
20670 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
20680 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
20690 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
206a0 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
206b0 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
206c0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
206d0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
206e0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
206f0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
20700 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
20710 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
20720 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
20730 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
20740 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63  3_open_v2() is c
20750 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
20760 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
20770 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
20780 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
20790 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
207a0 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
207b0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
207c0 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
207d0 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
207e0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
207f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
20800 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
20810 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
20820 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
20830 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
20840 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
20850 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
20860 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
20870 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
20880 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
20890 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
208a0 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
208b0 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
208c0 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
208d0 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
208e0 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
208f0 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
20900 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
20910 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
20920 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
20930 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
20940 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
20950 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
20960 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
20970 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
20980 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
20990 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
209a0 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
209b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
209c0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
209d0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
209e0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  ,.** and/or [SQL
209f0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
20a00 43 41 43 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a  CACHE] flags:)^.
20a10 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
20a20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
20a30 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
20a40 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
20a50 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
20a60 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
20a70 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
20a80 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
20a90 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
20aa0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
20ab0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
20ac0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
20ad0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
20ae0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
20af0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
20b00 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
20b10 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
20b20 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
20b30 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
20b40 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
20b50 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
20b60 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
20b70 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
20b80 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
20b90 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
20ba0 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
20bb0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
20bc0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
20bd0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
20be0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
20bf0 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
20c00 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
20c10 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
20c20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
20c30 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
20c40 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
20c50 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
20c60 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
20c70 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
20c80 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
20c90 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
20ca0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
20cb0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
20cc0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
20cd0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
20ce0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
20cf0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
20d00 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
20d10 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
20d20 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
20d30 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20  above or one of 
20d40 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  the combinations
20d50 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d   shown above com
20d60 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  bined.** with th
20d70 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
20d80 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
20d90 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
20da0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
20db0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 61  N_SHAREDCACHE] a
20dc0 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
20dd0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
20de0 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20   flags,.** then 
20df0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
20e00 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
20e10 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
20e20 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
20e30 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
20e40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
20e50 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
20e60 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
20e70 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
20e80 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
20e90 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
20ea0 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
20eb0 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
20ec0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
20ed0 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
20ee0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
20ef0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
20f00 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
20f10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
20f20 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
20f30 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
20f40 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
20f50 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
20f60 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
20f70 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
20f80 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
20f90 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
20fa0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
20fb0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
20fc0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
20fd0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
20fe0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
20ff0 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
21000 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
21010 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
21020 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
21030 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
21040 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
21050 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
21060 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
21070 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
21080 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
21090 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
210a0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
210b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
210c0 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
210d0 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
210e0 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
210f0 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
21100 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
21110 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
21120 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
21130 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
21140 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
21150 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
21160 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
21170 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
21180 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
21190 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
211a0 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
211b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
211c0 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
211d0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
211e0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
211f0 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
21200 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
21210 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
21220 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
21230 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
21240 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
21250 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
21260 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
21270 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
21280 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
21290 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
212a0 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
212b0 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
212c0 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
212d0 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
212e0 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
212f0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
21300 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
21310 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
21320 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
21330 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
21340 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
21350 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
21360 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
21370 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
21380 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
21390 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
213a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
213b0 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
213c0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
213d0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
213e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
213f0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
21400 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
21410 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
21420 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
21430 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
21440 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
21450 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
21460 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
21470 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
21480 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
21490 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
214a0 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
214b0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
214c0 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
214d0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
214e0 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
214f0 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
21500 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
21510 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
21520 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
21530 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
21540 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
21550 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
21560 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
21570 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
21580 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
21590 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
215a0 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
215b0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
215c0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
215d0 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
215e0 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
215f0 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
21600 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
21610 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 53  _open_v2()..*/.S
21620 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
21630 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
21640 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
21650 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
21660 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
21670 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
21680 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
21690 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
216a0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53  b handle */.);.S
216b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
216c0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
216d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
216e0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
216f0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
21700 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
21710 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
21720 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
21730 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
21740 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
21750 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21760 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
21770 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
21780 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
21790 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
217a0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
217b0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
217c0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
217d0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
217e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
217f0 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
21800 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
21810 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
21820 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
21830 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
21840 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
21850 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
21860 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
21870 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
21880 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
21890 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
218a0 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
218b0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
218c0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
218d0 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
218e0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
218f0 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
21900 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
21910 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
21920 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
21930 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
21940 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
21950 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
21960 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
21970 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
21980 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
21990 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
219a0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
219b0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
219c0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
219d0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
219e0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
219f0 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
21a00 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
21a10 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
21a20 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
21a30 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
21a40 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
21a50 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
21a60 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
21a70 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
21a80 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
21a90 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
21aa0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
21ab0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
21ac0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
21ad0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
21ae0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
21af0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
21b00 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
21b10 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
21b20 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
21b30 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
21b40 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
21b50 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
21b60 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
21b70 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
21b80 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
21b90 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
21ba0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
21bb0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
21bc0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
21bd0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
21be0 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ^.**.** When the
21bf0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
21c00 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
21c10 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
21c20 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
21c30 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
21c40 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
21c50 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
21c60 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
21c70 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
21c80 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
21c90 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
21ca0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
21cb0 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
21cc0 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
21cd0 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
21ce0 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
21cf0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
21d00 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
21d10 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
21d20 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
21d30 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
21d40 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
21d50 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
21d60 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
21d70 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
21d80 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
21d90 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
21da0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
21db0 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
21dc0 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
21dd0 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
21de0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
21df0 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
21e00 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
21e10 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
21e20 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
21e30 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
21e40 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
21e50 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
21e60 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
21e70 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
21e80 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
21e90 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
21ea0 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
21eb0 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
21ec0 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
21ed0 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
21ee0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
21ef0 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
21f00 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c  t be set..*/.SQL
21f10 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
21f20 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
21f30 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
21f40 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
21f50 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
21f60 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
21f70 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
21f80 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
21f90 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
21fa0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
21fb0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
21fc0 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
21fd0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
21fe0 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
21ff0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
22000 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
22010 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
22020 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
22030 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
22040 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
22050 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
22060 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
22070 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
22080 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
22090 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
220a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
220b0 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
220c0 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
220d0 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
220e0 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
220f0 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
22100 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
22110 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
22120 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
22130 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
22140 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
22150 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
22160 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
22170 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
22180 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
22190 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
221a0 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
221b0 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
221c0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
221d0 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
221e0 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
221f0 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
22200 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
22210 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
22220 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
22230 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
22240 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
22250 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
22260 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
22270 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
22280 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
22290 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
222a0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
222b0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
222c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
222d0 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
222e0 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
222f0 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
22300 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
22310 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
22320 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
22330 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
22340 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
22350 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
22360 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22370 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
22380 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
22390 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
223a0 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
223b0 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
223c0 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
223d0 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
223e0 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
223f0 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
22400 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
22410 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
22420 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
22430 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
22440 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
22450 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
22460 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
22470 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
22480 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
22490 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
224a0 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
224b0 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
224c0 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
224d0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
224e0 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
224f0 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a  at construct.)^.
22500 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65  **.** ^If the ne
22510 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
22520 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
22530 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
22540 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65  nged..** ^(For e
22550 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ach limit catego
22560 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ry SQLITE_LIMIT_
22570 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72  <i>NAME</i> ther
22580 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69  e is a .** [limi
22590 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20  ts | hard upper 
225a0 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74  bound].** set at
225b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79   compile-time by
225c0 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f   a C preprocesso
225d0 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a  r macro called.*
225e0 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49  * [limits | SQLI
225f0 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f  TE_MAX_<i>NAME</
22600 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  i>]..** (The "_L
22610 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
22620 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
22630 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20   "_MAX_".))^.** 
22640 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63  ^Attempts to inc
22650 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
22660 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
22670 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
22680 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
22690 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
226a0 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a  pper bound..**.*
226b0 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66  * ^Regardless of
226c0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
226d0 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68  the limit was ch
226e0 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b  anged, the .** [
226f0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
22700 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
22710 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ns the prior val
22720 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e  ue of the limit.
22730 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66  .** ^Hence, to f
22740 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  ind the current 
22750 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74  value of a limit
22760 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e   without changin
22770 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20  g it,.** simply 
22780 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65  invoke this inte
22790 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74  rface with the t
227a0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73  hird parameter s
227b0 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20  et to -1..**.** 
227c0 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
227d0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
227e0 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
227f0 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
22800 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
22810 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
22820 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
22830 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
22840 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
22850 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
22860 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
22870 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
22880 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
22890 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
228a0 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
228b0 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
228c0 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
228d0 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
228e0 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
228f0 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
22900 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
22910 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
22920 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
22930 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
22940 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
22950 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
22960 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
22970 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
22980 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
22990 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
229a0 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
229b0 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
229c0 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
229d0 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
229e0 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
229f0 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
22a00 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
22a10 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
22a20 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
22a30 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
22a40 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
22a50 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
22a60 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
22a70 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
22a80 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
22a90 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
22aa0 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
22ab0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
22ac0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
22ad0 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
22ae0 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
22af0 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
22b00 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
22b10 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51   releases..*/.SQ
22b20 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
22b30 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
22b40 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
22b50 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
22b60 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
22b70 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
22b80 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
22b90 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
22ba0 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
22bb0 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
22bc0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
22bd0 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
22be0 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
22bf0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
22c00 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
22c10 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
22c20 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
22c30 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
22c40 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
22c50 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
22c60 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
22c70 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
22c80 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
22c90 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
22ca0 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
22cb0 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
22cc0 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  l>.** ^(<dt>SQLI
22cd0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
22ce0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
22cf0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
22d00 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
22d10 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
22d20 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
22d30 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
22d40 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
22d50 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
22d60 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
22d70 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
22d80 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
22d90 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
22da0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
22db0 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
22dc0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
22dd0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
22de0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
22df0 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
22e00 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
22e10 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
22e20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
22e30 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
22e40 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
22e50 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
22e60 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
22e70 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
22e80 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
22e90 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
22ea0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
22eb0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
22ec0 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
22ed0 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
22ee0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
22ef0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
22f00 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
22f10 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
22f20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
22f30 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
22f40 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
22f50 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
22f60 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
22f70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
22f80 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
22f90 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
22fa0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
22fb0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
22fc0 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
22fd0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
22fe0 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
22ff0 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
23000 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
23010 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
23020 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
23030 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
23040 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
23050 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
23060 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
23070 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
23080 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
23090 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
230a0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
230b0 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
230c0 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
230d0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
230e0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
230f0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
23100 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
23110 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
23120 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
23130 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
23140 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
23150 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
23160 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
23170 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
23180 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
23190 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
231a0 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
231b0 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
231c0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
231d0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
231e0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
231f0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
23200 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
23210 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
23220 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
23230 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
23240 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
23250 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
23260 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
23270 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
23280 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
23290 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
232a0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
232b0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
232c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
232d0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
232e0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
232f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
23300 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
23310 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
23320 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
23330 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
23340 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
23350 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
23360 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
23370 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
23380 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
23390 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
233a0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
233b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
233c0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
233d0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
233e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
233f0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
23400 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
23410 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
23420 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
23430 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
23440 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
23450 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
23460 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
23470 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
23480 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
23490 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
234a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
234b0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
234c0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
234d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
234e0 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
234f0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
23500 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
23510 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
23520 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
23530 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
23540 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
23550 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
23560 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
23570 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
23580 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
23590 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
235a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
235b0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
235c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
235d0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
235e0 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
235f0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
23600 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
23610 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23620 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
23630 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
23640 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
23650 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
23660 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
23670 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
23680 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
23690 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
236a0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
236b0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
236c0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
236d0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
236e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
236f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
23700 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
23710 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
23720 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
23730 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
23740 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
23750 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
23760 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
23770 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
23780 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
23790 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
237a0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
237b0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
237c0 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
237d0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
237e0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
237f0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
23800 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
23810 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
23820 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
23830 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
23840 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
23850 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
23860 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
23870 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
23880 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
23890 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
238a0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
238b0 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
238c0 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
238d0 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
238e0 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
238f0 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
23900 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
23910 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
23920 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
23930 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
23940 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
23950 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
23960 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
23970 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
23980 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
23990 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
239a0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
239b0 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a  minator bytes..*
239c0 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20  *.** ^If pzTail 
239d0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
239e0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
239f0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
23a00 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70   first byte.** p
23a10 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
23a20 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
23a30 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
23a40 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
23a50 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20  only.** compile 
23a60 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
23a70 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
23a80 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
23a90 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77  pointing to.** w
23aa0 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
23ab0 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a  mpiled..**.** ^*
23ac0 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
23ad0 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
23ae0 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
23af0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
23b00 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
23b10 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
23b20 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20  3_step()].  ^If 
23b30 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
23b40 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  r, *ppStmt is se
23b50 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e  t.** to NULL.  ^
23b60 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78  If the input tex
23b70 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  t contains no SQ
23b80 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
23b90 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73  is an empty.** s
23ba0 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
23bb0 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
23bc0 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
23bd0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  .** The calling 
23be0 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
23bf0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
23c00 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
23c10 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
23c20 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
23c30 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
23c40 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
23c50 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
23c60 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20   ppStmt may not 
23c70 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
23c80 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20  On success, the 
23c90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
23ca0 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74  ) family of rout
23cb0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
23cc0 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65  ITE_OK];.** othe
23cd0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
23ce0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
23cf0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
23d00 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
23d10 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
23d20 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
23d30 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
23d40 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
23d50 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
23d60 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
23d70 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
23d80 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
23d90 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
23da0 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
23db0 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
23dc0 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ged..** ^In the 
23dd0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "v2" interfaces,
23de0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
23df0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
23e00 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
23e10 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
23e20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
23e30 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
23e40 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
23e50 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
23e60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
23e70 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
23e80 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66  to.** behave dif
23e90 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65  ferently in thre
23ea0 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e ways:.**.** <o
23eb0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  l>.** <li>.** ^I
23ec0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
23ed0 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
23ee0 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
23ef0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
23f00 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
23f10 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
23f20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23f30 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
23f40 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
23f50 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
23f60 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
23f70 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c  n it again..** <
23f80 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
23f90 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
23fa0 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
23fb0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
23fc0 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
23fd0 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
23fe0 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
23ff0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
24000 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
24010 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
24020 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
24030 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
24040 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
24050 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
24060 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
24070 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c  .** and the appl
24080 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61  ication would ha
24090 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
240a0 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
240b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
240c0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
240d0 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
240e0 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
240f0 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
24100 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
24110 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
24120 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
24130 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
24140 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
24150 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
24160 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
24170 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63  ^If the specific
24180 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20   value bound to 
24190 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73  [parameter | hos
241a0 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  t parameter] in 
241b0 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c  the .** WHERE cl
241c0 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75  ause might influ
241d0 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20  ence the choice 
241e0 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f  of query plan fo
241f0 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a  r a statement,.*
24200 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  * then the state
24210 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74  ment will be aut
24220 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
24230 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65  piled, as if the
24240 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20  re had been .** 
24250 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c  a schema change,
24260 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b   on the first  [
24270 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
24280 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  call following a
24290 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20  ny change.** to 
242a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
242b0 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67  d_text | binding
242c0 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61  s] of that [para
242d0 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65  meter]. .** ^The
242e0 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
242f0 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20  of WHERE-clause 
24300 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68  [parameter] migh
24310 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
24320 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75  .** choice of qu
24330 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20  ery plan if the 
24340 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
24350 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
24360 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f  of a [LIKE].** o
24370 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  r [GLOB] operato
24380 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61  r or if the para
24390 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65  meter is compare
243a0 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20  d to an indexed 
243b0 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68  column.** and th
243c0 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
243d0 5f 53 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65 2d  _STAT2] compile-
243e0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
243f0 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a  nabled..** the .
24400 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
24410 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  >.*/.SQLITE_API 
24420 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
24430 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
24440 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
24450 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
24460 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
24470 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
24480 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
24490 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
244a0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
244b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
244c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
244d0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
244e0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
244f0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
24500 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
24510 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
24520 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
24530 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
24540 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
24550 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
24560 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
24570 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
24580 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
24590 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
245a0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
245b0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
245c0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
245d0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
245e0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
245f0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
24600 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
24610 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
24620 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
24630 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
24640 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
24650 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
24660 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
24670 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
24680 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
24690 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
246a0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
246b0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
246c0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
246d0 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
246e0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
246f0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
24700 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
24710 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
24720 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
24730 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
24740 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
24750 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
24760 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
24770 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
24780 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
24790 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
247a0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
247b0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
247c0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
247d0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
247e0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
247f0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
24800 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
24810 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
24820 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69  are16_v2(.  sqli
24830 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
24840 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
24850 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
24860 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
24870 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
24880 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
24890 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
248a0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
248b0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
248c0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
248d0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
248e0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
248f0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
24900 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
24910 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
24920 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
24930 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
24940 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
24950 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
24960 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
24970 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53  ving Statement S
24980 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  QL.**.** ^This i
24990 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
249a0 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
249b0 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
249c0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
249d0 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
249e0 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
249f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24a00 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  if that statemen
24a10 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  t was.** compile
24a20 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
24a30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
24a40 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
24a50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
24a60 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
24a70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
24a80 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
24a90 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
24aa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24ab0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
24ac0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
24ad0 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
24ae0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
24af0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
24b00 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
24b10 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
24b20 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
24b30 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
24b40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24b50 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
24b60 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
24b70 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
24b80 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
24b90 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
24ba0 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
24bb0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
24bc0 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
24bd0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
24be0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
24bf0 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
24c00 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
24c10 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
24c20 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
24c30 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
24c40 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
24c50 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
24c60 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
24c70 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
24c80 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
24c90 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
24ca0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
24cb0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
24cc0 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
24cd0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
24ce0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
24cf0 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
24d00 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
24d10 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
24d20 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
24d30 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
24d40 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
24d50 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
24d60 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
24d70 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
24d80 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
24d90 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
24da0 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
24db0 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
24dc0 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
24dd0 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
24de0 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
24df0 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
24e00 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
24e10 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
24e20 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
24e30 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
24e40 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
24e50 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
24e60 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
24e70 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
24e80 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
24e90 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
24ea0 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
24eb0 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
24ec0 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
24ed0 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
24ee0 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
24ef0 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
24f00 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
24f10 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
24f20 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
24f30 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
24f40 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
24f50 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
24f60 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
24f70 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
24f80 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
24f90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24fa0 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
24fb0 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
24fc0 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
24fd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
24fe0 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
24ff0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
25000 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
25010 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
25020 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
25030 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
25040 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
25050 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
25060 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
25070 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
25080 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
25090 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
250a0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
250b0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
250c0 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
250d0 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
250e0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
250f0 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
25100 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
25110 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
25120 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
25130 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
25140 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
25150 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
25160 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
25170 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
25180 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
25190 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
251a0 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
251b0 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
251c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
251d0 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
251e0 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
251f0 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
25200 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
25210 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
25220 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
25230 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
25240 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
25250 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
25260 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
25270 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
25280 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
25290 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
252a0 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
252b0 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
252c0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
252d0 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
252e0 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
252f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
25300 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
25310 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
25320 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
25330 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
25340 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
25350 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
25360 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
25370 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
25380 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
25390 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
253a0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
253b0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
253c0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
253d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
253e0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
253f0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
25400 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
25410 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
25420 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
25430 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
25440 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
25450 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
25460 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
25470 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
25480 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
25490 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
254a0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
254b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
254c0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
254d0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
254e0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
254f0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
25500 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
25510 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
25520 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
25530 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
25540 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
25550 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
25560 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
25570 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
25580 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
25590 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
255a0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
255b0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
255c0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
255d0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
255e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
255f0 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
25600 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
25610 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
25620 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
25630 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
25640 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
25650 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
25660 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
25670 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
25680 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
25690 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
256a0 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
256b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
256c0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
256d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
256e0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
256f0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
25700 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
25710 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
25720 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
25730 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
25740 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
25750 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
25760 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
25770 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
25780 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
25790 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
257a0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
257b0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
257c0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
257d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
257e0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
257f0 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
25800 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
25810 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
25820 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
25830 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
25840 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
25850 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
25860 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
25870 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
25880 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
25890 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
258a0 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
258b0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
258c0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
258d0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
258e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
258f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
25900 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
25910 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
25920 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
25930 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
25940 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
25950 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
25960 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
25970 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
25980 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
25990 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
259a0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
259b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
259c0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
259d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
259e0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
259f0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
25a00 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
25a10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
25a20 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
25a30 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
25a40 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
25a50 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
25a60 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
25a70 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
25a80 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
25a90 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
25aa0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
25ab0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
25ac0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
25ad0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
25ae0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
25af0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
25b00 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
25b10 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
25b20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
25b30 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
25b40 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
25b50 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
25b60 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
25b70 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
25b80 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
25b90 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
25ba0 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
25bb0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
25bc0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
25bd0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
25be0 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
25bf0 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
25c00 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
25c10 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
25c20 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
25c30 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
25c40 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
25c50 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
25c60 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
25c70 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
25c80 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
25c90 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
25ca0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
25cb0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
25cc0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
25cd0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
25ce0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
25cf0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
25d00 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
25d10 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
25d20 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
25d30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
25d40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
25d50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
25d60 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
25d70 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
25d80 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
25d90 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
25da0 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
25db0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25dc0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
25dd0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
25de0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
25df0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
25e00 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
25e10 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
25e20 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
25e30 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
25e40 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
25e50 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
25e60 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
25e70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
25e80 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
25e90 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
25ea0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
25eb0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
25ec0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
25ed0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
25ee0 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
25ef0 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
25f00 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
25f10 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
25f20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
25f30 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
25f40 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
25f50 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
25f60 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
25f70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
25f80 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
25f90 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
25fa0 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
25fb0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
25fc0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
25fd0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
25fe0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
25ff0 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
26000 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
26010 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
26020 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
26030 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
26040 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
26050 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
26060 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
26070 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
26080 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
26090 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
260a0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
260b0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
260c0 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
260d0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
260e0 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
260f0 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
26100 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
26110 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
26120 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
26130 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
26140 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
26150 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
26160 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
26170 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
26180 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
26190 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
261a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
261b0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
261c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
261d0 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
261e0 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
261f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
26200 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
26210 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
26220 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
26230 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
26240 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
26250 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
26260 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
26270 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  r is called.** t
26280 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
26290 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
262a0 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  even if the call
262b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
262c0 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69  _blob(),.** sqli
262d0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
262e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
262f0 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e  _text16() fails.
26300 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69    .** ^If the fi
26310 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
26320 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
26330 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
26340 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
26350 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
26360 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
26370 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
26380 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
26390 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
263a0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
263b0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
263c0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
263d0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
263e0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
263f0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
26400 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
26410 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
26420 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
26430 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
26440 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
26450 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
26460 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
26470 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
26480 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
26490 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
264a0 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
264b0 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
264c0 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
264d0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
264e0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
264f0 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
26500 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
26510 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
26520 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
26530 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
26540 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
26550 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
26560 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
26570 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
26580 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
26590 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
265a0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
265b0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
265c0 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
265d0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
265e0 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
265f0 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
26600 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
26610 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
26620 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
26630 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
26640 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
26650 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
26660 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
26670 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
26680 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
26690 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
266a0 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
266b0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
266c0 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
266d0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
266e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
266f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
26700 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
26710 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
26720 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
26730 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
26740 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
26750 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26760 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
26770 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
26780 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
26790 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
267a0 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
267b0 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
267c0 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
267d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
267e0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
267f0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
26800 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
26810 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
26820 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
26830 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
26840 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
26850 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
26860 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
26870 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
26880 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
26890 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
268a0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
268b0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
268c0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
268d0 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
268e0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
268f0 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
26900 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
26910 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
26920 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
26930 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
26940 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
26950 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
26960 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26970 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
26980 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
26990 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
269a0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
269b0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
269c0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
269d0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
269e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
269f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
26a00 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
26a10 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
26a20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
26a30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
26a40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
26a50 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  nt, int);.SQLITE
26a60 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
26a70 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
26a80 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
26a90 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
26aa0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
26ab0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
26ac0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26ad0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
26ae0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
26af0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
26b00 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
26b10 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
26b20 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
26b30 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
26b40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
26b50 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
26b60 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
26b70 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
26b80 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
26b90 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
26ba0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
26bb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
26bc0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
26bd0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
26be0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
26bf0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
26c00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
26c10 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
26c20 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
26c30 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
26c40 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
26c50 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
26c60 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
26c70 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
26c80 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
26c90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26ca0 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
26cb0 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
26cc0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
26cd0 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
26ce0 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
26cf0 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
26d00 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
26d10 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
26d20 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
26d30 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
26d40 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
26d50 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
26d60 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
26d70 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
26d80 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
26d90 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
26da0 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
26db0 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
26dc0 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
26dd0 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
26de0 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
26df0 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
26e00 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
26e10 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
26e20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
26e30 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
26e40 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
26e50 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
26e60 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
26e70 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
26e80 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
26e90 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
26ea0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26eb0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
26ec0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
26ed0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
26ee0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
26ef0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
26f00 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
26f10 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
26f20 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
26f30 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
26f40 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
26f50 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ter.**.** ^The s
26f60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
26f70 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
26f80 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
26f90 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
26fa0 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
26fb0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
26fc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26fd0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
26fe0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
26ff0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
27000 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
27010 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
27020 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
27030 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
27040 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
27050 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
27060 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
27070 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
27080 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
27090 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
270a0 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
270b0 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
270c0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
270d0 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
270e0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
270f0 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
27100 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
27110 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
27120 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
27130 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
27140 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
27150 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
27160 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
27170 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
27180 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
27190 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
271a0 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
271b0 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
271c0 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
271d0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
271e0 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
271f0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
27200 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
27210 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
27220 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
27230 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
27240 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
27250 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
27260 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
27270 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
27280 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
27290 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
272a0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
272b0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
272c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
272d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
272e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
272f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
27300 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
27310 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
27320 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
27330 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
27340 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
27350 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
27360 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
27370 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
27380 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
27390 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
273a0 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
273b0 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  e.**.** ^Return 
273c0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
273d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
273e0 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
273f0 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
27400 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
27410 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
27420 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
27430 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
27440 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
27450 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
27460 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
27470 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
27480 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
27490 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
274a0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
274b0 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
274c0 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
274d0 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
274e0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
274f0 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
27500 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
27510 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
27520 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
27530 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
27540 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
27550 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
27560 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
27570 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
27580 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
27590 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
275a0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
275b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
275c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
275d0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
275e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
275f0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
27600 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27610 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
27620 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
27630 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
27640 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
27650 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
27660 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
27670 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
27680 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
27690 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
276a0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
276b0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
276c0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
276d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
276e0 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
276f0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
27700 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  L..*/.SQLITE_API
27710 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65   int sqlite3_cle
27720 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
27730 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
27740 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
27750 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
27760 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
27770 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
27780 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
27790 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
277a0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
277b0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
277c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
277d0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
277e0 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
277f0 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
27800 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
27810 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
27820 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
27830 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
27840 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
27850 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
27860 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
27870 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
27880 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
27890 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
278a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
278b0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
278c0 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
278d0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
278e0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
278f0 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
27900 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
27910 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
27920 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
27930 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
27940 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
27950 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
27960 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27970 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
27980 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
27990 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
279a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
279b0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
279c0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
279d0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
279e0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
279f0 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
27a00 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
27a10 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
27a20 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
27a30 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
27a40 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
27a50 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
27a60 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
27a70 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
27a80 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
27a90 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
27aa0 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
27ab0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
27ac0 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
27ad0 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
27ae0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27af0 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
27b00 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
27b10 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
27b20 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
27b30 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
27b40 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
27b50 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
27b60 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
27b70 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
27b80 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
27b90 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
27ba0 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
27bb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
27bc0 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
27bd0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
27be0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
27bf0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
27c00 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
27c10 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
27c20 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
27c30 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
27c40 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
27c50 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
27c60 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
27c70 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
27c80 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
27c90 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
27ca0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
27cb0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
27cc0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
27cd0 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
27ce0 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
27cf0 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
27d00 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
27d10 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
27d20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
27d30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
27d40 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
27d50 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
27d60 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
27d70 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
27d80 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
27d90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
27da0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
27db0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
27dc0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
27dd0 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  N);.SQLITE_API c
27de0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
27df0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
27e00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27e10 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
27e20 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
27e30 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
27e40 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
27e50 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
27e60 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
27e70 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
27e80 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
27e90 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
27ea0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
27eb0 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
27ec0 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
27ed0 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
27ee0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
27ef0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
27f00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
27f10 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
27f20 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
27f30 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
27f40 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
27f50 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
27f60 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
27f70 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
27f80 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
27f90 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
27fa0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
27fb0 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
27fc0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
27fd0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
27fe0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
27ff0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
28000 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
28010 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
28020 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
28030 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
28040 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
28050 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
28060 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
28070 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
28080 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
28090 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
280a0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
280b0 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
280c0 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
280d0 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
280e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
280f0 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
28100 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
28110 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
28120 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75   ^The names retu
28130 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
28140 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
28150 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
28160 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
28170 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
28180 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
28190 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65  rgument to these
281a0 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61   interfaces is a
281b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
281c0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65  ment]..** ^These
281d0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
281e0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
281f0 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75  out the Nth resu
28200 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  lt column return
28210 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
28220 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
28230 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
28240 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
28250 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f  .** ^The left-mo
28260 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c  st column is col
28270 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20  umn 0 for these 
28280 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
28290 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
282a0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
282b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
282c0 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
282d0 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
282e0 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
282f0 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
28300 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
28310 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
28320 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  LL.  ^These rout
28330 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  ine might also r
28340 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20  eturn NULL if a 
28350 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
28360 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72  n error.** occur
28370 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20  s.  ^Otherwise, 
28380 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
28390 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
283a0 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
283b0 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75  able,.** or colu
283c0 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
283d0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
283e0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
283f0 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61  **.** ^As with a
28400 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
28410 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73  APIs, those whos
28420 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68  e names end with
28430 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
28440 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
28450 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f  trings and the o
28460 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
28470 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
28480 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61  ** ^These APIs a
28490 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
284a0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
284b0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
284c0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
284d0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
284e0 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
284f0 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e  rocessor symbol.
28500 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
28510 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
28520 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
28530 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
28540 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
28550 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
28560 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
28570 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
28580 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
28590 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
285a0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
285b0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
285c0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
285d0 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
285e0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
285f0 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
28600 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
28610 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
28620 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
28630 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
28640 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
28650 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
28660 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
28670 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
28680 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
28690 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
286a0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
286b0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
286c0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
286d0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
286e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
286f0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
28700 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
28710 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
28720 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
28730 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
28740 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
28750 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
28760 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
28770 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28780 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
28790 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
287a0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
287b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
287c0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
287d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
287e0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
287f0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
28800 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
28810 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
28820 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
28830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
28840 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
28850 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
28860 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  lt.**.** ^(The f
28870 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
28880 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
28890 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
288a0 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
288b0 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
288c0 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
288d0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
288e0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
288f0 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
28900 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
28910 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
28920 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
28930 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
28940 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
28950 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
28960 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
28970 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
28980 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
28990 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
289a0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
289b0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
289c0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
289d0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
289e0 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
289f0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
28a00 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
28a10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
28a20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
28a30 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
28a40 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
28a50 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
28a60 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
28a70 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
28a80 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
28a90 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
28aa0 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
28ab0 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
28ac0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
28ad0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
28ae0 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
28af0 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
28b00 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
28b10 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
28b20 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
28b30 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
28b40 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
28b50 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
28b60 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
28b70 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
28b80 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
28b90 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
28ba0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
28bb0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
28bc0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
28bd0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
28be0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
28bf0 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
28c00 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
28c10 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
28c20 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
28c30 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
28c40 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
28c50 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
28c60 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
28c70 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
28c80 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
28c90 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
28ca0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
28cb0 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51  se values..*/.SQ
28cc0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
28cd0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
28ce0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
28cf0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
28d00 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
28d10 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
28d20 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
28d30 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
28d40 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
28d50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
28d60 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
28d70 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
28d80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28d90 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
28da0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
28db0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
28dc0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
28dd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28de0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
28df0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
28e00 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
28e10 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
28e20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
28e30 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
28e40 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
28e50 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
28e60 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
28e70 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
28e80 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
28e90 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
28ea0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
28eb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
28ec0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
28ed0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
28ee0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
28ef0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
28f00 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
28f10 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
28f20 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
28f30 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
28f40 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
28f50 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
28f60 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
28f70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28f80 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
28f90 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
28fa0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
28fb0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
28fc0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
28fd0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
28fe0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
28ff0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
29000 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
29010 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
29020 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
29030 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
29040 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
29050 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
29060 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
29070 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
29080 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
29090 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
290a0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
290b0 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
290c0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
290d0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
290e0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
290f0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
29100 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
29110 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
29120 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
29130 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
29140 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
29150 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
29160 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
29170 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
29180 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
29190 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
291a0 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
291b0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
291c0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
291d0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
291e0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
291f0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
29200 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
29210 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
29220 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
29230 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
29240 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
29250 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
29260 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
29270 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
29280 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
29290 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
292a0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
292b0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
292c0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
292d0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
292e0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
292f0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
29300 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
29310 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
29320 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
29330 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
29340 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
29350 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
29360 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
29370 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
29380 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
29390 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
293a0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
293b0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
293c0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
293d0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
293e0 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
293f0 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
29400 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
29410 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
29420 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
29430 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
29440 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
29450 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
29460 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
29470 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
29480 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
29490 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
294a0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
294b0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
294c0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
294d0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
294e0 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
294f0 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
29500 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
29510 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
29520 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
29530 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
29540 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
29550 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
29560 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
29570 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
29580 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
29590 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
295a0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
295b0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
295c0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
295d0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
295e0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
295f0 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
29600 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
29610 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
29620 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
29630 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
29640 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
29650 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
29660 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
29670 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
29680 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
29690 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
296a0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
296b0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
296c0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
296d0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
296e0 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
296f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
29700 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
29710 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
29720 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
29730 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
29740 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
29750 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
29760 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
29770 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
29780 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
29790 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
297a0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
297b0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
297c0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
297d0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
297e0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
297f0 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
29800 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
29810 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
29820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
29830 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
29840 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
29850 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
29860 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
29870 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
29880 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
29890 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
298a0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
298b0 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
298c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
298d0 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
298e0 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
298f0 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
29900 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
29910 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
29920 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
29930 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
29940 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
29950 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
29960 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
29970 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29980 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
29990 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
299a0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
299b0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
299c0 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
299d0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
299e0 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
299f0 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
29a00 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
29a10 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
29a20 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
29a30 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
29a40 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
29a50 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
29a60 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
29a70 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
29a80 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
29a90 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
29aa0 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
29ab0 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
29ac0 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
29ad0 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
29ae0 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
29af0 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
29b00 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
29b10 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
29b20 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
29b30 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
29b40 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
29b50 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
29b60 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
29b70 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
29b80 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
29b90 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
29ba0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
29bb0 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
29bc0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
29bd0 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
29be0 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
29bf0 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
29c00 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
29c10 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
29c20 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
29c30 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
29c40 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
29c50 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
29c60 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
29c70 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
29c80 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
29c90 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
29ca0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
29cb0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
29cc0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
29cd0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
29ce0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
29cf0 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
29d00 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
29d10 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
29d20 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
29d30 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
29d40 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
29d50 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
29d60 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
29d70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
29d80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
29d90 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
29da0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
29db0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
29dc0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
29dd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
29de0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
29df0 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
29e00 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
29e10 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
29e20 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
29e30 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
29e40 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
29e50 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
29e60 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
29e70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
29e80 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
29e90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
29ea0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29eb0 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
29ec0 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
29ed0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
29ee0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
29ef0 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
29f00 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
29f10 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
29f20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
29f30 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
29f40 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
29f50 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
29f60 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
29f70 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
29f80 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
29f90 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
29fa0 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
29fb0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
29fc0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
29fd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
29fe0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
29ff0 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
2a000 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
2a010 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
2a020 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2a030 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
2a040 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
2a050 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
2a060 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  nter..**.** See 
2a070 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
2a080 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
2a090 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2a0a0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2a0b0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2a0c0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2a0d0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
2a0e0 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
2a0f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
2a100 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
2a110 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
2a120 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
2a130 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
2a140 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
2a150 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2a160 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
2a170 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
2a180 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
2a190 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2a1a0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
2a1b0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
2a1c0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
2a1d0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
2a1e0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
2a1f0 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
2a200 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
2a210 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
2a220 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
2a230 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
2a240 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
2a250 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
2a260 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
2a270 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
2a280 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
2a290 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
2a2a0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
2a2b0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
2a2c0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
2a2d0 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
2a2e0 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
2a2f0 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
2a300 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
2a310 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
2a320 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
2a330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
2a340 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
2a350 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
2a360 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
2a370 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
2a380 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
2a390 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2a3a0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
2a3b0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
2a3c0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
2a3d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2a3e0 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
2a3f0 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
2a400 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
2a410 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
2a420 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2a430 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
2a440 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
2a450 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
2a460 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2a470 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2a480 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
2a490 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
2a4a0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
2a4b0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
2a4c0 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
2a4d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2a4e0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
2a4f0 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
2a500 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2a510 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
2a520 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
2a530 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
2a540 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
2a550 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
2a560 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
2a570 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
2a580 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
2a590 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2a5a0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2a5b0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
2a5c0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
2a5d0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
2a5e0 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
2a5f0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
2a600 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
2a610 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
2a620 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
2a630 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2a640 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
2a650 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
2a660 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2a670 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
2a680 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
2a690 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2a6a0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
2a6b0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
2a6c0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
2a6d0 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
2a6e0 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
2a6f0 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
2a700 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
2a710 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
2a720 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
2a730 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2a740 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2a750 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2a760 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2a770 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
2a780 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2a790 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
2a7a0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
2a7b0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
2a7c0 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
2a7d0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
2a7e0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2a7f0 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
2a800 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2a810 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2a820 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
2a830 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2a840 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
2a850 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
2a860 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2a870 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
2a880 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2a890 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
2a8a0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2a8b0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2a8c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2a8d0 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
2a8e0 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
2a8f0 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
2a900 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2a910 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
2a920 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
2a930 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2a940 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2a950 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a960 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
2a970 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
2a980 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2a990 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
2a9a0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
2a9b0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
2a9c0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
2a9d0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2a9e0 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
2a9f0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
2aa00 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
2aa10 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
2aa20 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
2aa30 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
2aa40 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
2aa50 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2aa60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2aa70 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
2aa80 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
2aa90 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
2aaa0 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
2aab0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
2aac0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
2aad0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
2aae0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
2aaf0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2ab00 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2ab10 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
2ab20 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
2ab30 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
2ab40 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
2ab50 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
2ab60 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
2ab70 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
2ab80 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
2ab90 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2aba0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2abb0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
2abc0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2abd0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
2abe0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2abf0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2ac00 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2ac10 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2ac20 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2ac30 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
2ac40 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2ac50 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
2ac60 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2ac70 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
2ac80 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2ac90 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2aca0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2acb0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2acc0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2acd0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2ace0 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2acf0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2ad00 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2ad10 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
2ad20 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2ad30 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2ad40 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2ad50 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2ad60 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2ad70 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2ad80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2ad90 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2ada0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2adb0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2adc0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
2add0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2ade0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
2adf0 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2ae00 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2ae10 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2ae20 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2ae30 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2ae40 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
2ae50 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2ae60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2ae70 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2ae80 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2ae90 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
2aea0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2aeb0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2aec0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2aed0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2aee0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2aef0 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
2af00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2af10 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2af20 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2af30 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
2af40 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2af50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2af60 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2af70 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2af80 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2af90 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2afa0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
2afb0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2afc0 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
2afd0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2afe0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2aff0 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
2b000 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2b010 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
2b020 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
2b030 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
2b040 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
2b050 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
2b060 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
2b070 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2b080 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2b090 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
2b0a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2b0b0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
2b0c0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
2b0d0 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
2b0e0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2b0f0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
2b100 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
2b110 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2b120 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2b130 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2b140 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
2b150 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
2b160 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
2b170 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e  zero terminated.
2b180 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
2b190 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
2b1a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2b1b0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
2b1c0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
2b1d0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
2b1e0 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  * ^The object re
2b1f0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2b200 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2b210 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
2b220 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2b230 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
2b240 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
2b250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2b260 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
2b270 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
2b280 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2b290 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2b2a0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2b2b0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
2b2c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b2d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2b2e0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2b2f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2b300 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
2b310 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
2b320 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
2b330 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
2b340 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
2b350 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
2b360 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2b370 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
2b380 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2b390 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
2b3a0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2b3b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
2b3c0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
2b3d0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
2b3e0 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
2b3f0 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
2b400 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
2b410 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
2b420 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
2b430 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
2b440 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
2b450 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
2b460 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
2b470 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
2b480 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
2b490 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
2b4a0 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
2b4b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
2b4c0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
2b4d0 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
2b4e0 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
2b4f0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2b500 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
2b510 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
2b520 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
2b530 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
2b540 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
2b550 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
2b560 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2b570 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2b580 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2b590 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
2b5a0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
2b5b0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
2b5c0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
2b5d0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2b5e0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2b5f0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
2b600 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
2b610 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2b620 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2b630 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
2b640 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
2b650 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2b660 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2b670 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2b680 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
2b690 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
2b6a0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
2b6b0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2b6c0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2b6d0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
2b6e0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2b6f0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2b700 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
2b710 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
2b720 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2b730 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2b740 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66  > Convert from f
2b750 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a  loat to integer.
2b760 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2b770 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
2b780 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
2b790 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
2b7a0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2b7b0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2b7c0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
2b7d0 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45  ame as FLOAT->TE
2b7e0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
2b7f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
2b800 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20  EGER   <td> Use 
2b810 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
2b820 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2b830 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2b840 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  Use atof().** <t
2b850 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2b860 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2b870 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
2b880 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2b890 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2b8a0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
2b8b0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
2b8c0 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
2b8d0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2b8e0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2b8f0 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
2b900 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a  then use atof().
2b910 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2b920 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
2b930 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
2b940 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
2b950 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
2b960 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
2b970 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  uote>)^.**.** Th
2b980 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61  e table above ma
2b990 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f  kes reference to
2b9a0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
2b9b0 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74  ary functions at
2b9c0 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66  oi().** and atof
2b9d0 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73  ().  SQLite does
2b9e0 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20   not really use 
2b9f0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
2ba00 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20    It has its.** 
2ba10 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69  own equivalent i
2ba20 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
2ba30 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
2ba40 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
2ba50 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
2ba60 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
2ba70 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
2ba80 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
2ba90 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
2baa0 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
2bab0 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
2bac0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2bad0 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
2bae0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
2baf0 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
2bb00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2bb10 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
2bb20 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
2bb30 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
2bb40 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2bb50 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
2bb60 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
2bb70 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
2bb80 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
2bb90 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
2bba0 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
2bbb0 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
2bbc0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
2bbd0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2bbe0 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
2bbf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2bc00 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
2bc10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2bc20 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
2bc30 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
2bc40 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
2bc50 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
2bc60 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
2bc70 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
2bc80 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2bc90 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
2bca0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
2bcb0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
2bcc0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2bcd0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2bce0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2bcf0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2bd00 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2bd10 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
2bd20 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2bd30 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2bd40 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
2bd50 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2bd60 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2bd70 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2bd80 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
2bd90 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
2bda0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
2bdb0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
2bdc0 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
2bdd0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
2bde0 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
2bdf0 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
2be00 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
2be10 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
2be20 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
2be30 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
2be40 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
2be50 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
2be60 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
2be70 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
2be80 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
2be90 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
2bea0 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
2beb0 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
2bec0 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
2bed0 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
2bee0 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
2bef0 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
2bf00 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
2bf10 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
2bf20 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
2bf30 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
2bf40 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
2bf50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
2bf60 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
2bf70 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
2bf80 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
2bf90 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2bfa0 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
2bfb0 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
2bfc0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
2bfd0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2bfe0 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
2bff0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2c000 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2c010 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2c020 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
2c030 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2c040 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
2c050 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
2c060 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c070 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
2c080 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c090 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
2c0a0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
2c0b0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
2c0c0 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
2c0d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c0e0 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
2c0f0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
2c100 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2c110 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
2c120 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
2c130 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
2c140 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
2c150 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
2c160 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c170 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2c180 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c190 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
2c1a0 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
2c1b0 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
2c1c0 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
2c1d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2c1e0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2c1f0 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
2c200 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2c210 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2c220 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
2c230 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
2c240 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2c250 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
2c260 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2c270 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
2c280 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
2c290 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
2c2a0 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
2c2b0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
2c2c0 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
2c2d0 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
2c2e0 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
2c2f0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2c300 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2c310 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2c320 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
2c330 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
2c340 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
2c350 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
2c360 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
2c370 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
2c380 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
2c390 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
2c3a0 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  urned.** [sqlite
2c3b0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
2c3c0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
2c3d0 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
2c3e0 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
2c3f0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
2c400 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
2c410 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
2c420 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
2c430 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
2c440 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
2c450 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
2c460 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
2c470 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
2c480 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
2c490 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
2c4a0 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
2c4b0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
2c4c0 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
2c4d0 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
2c4e0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
2c4f0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2c500 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
2c510 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
2c520 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
2c530 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2c540 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2c550 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2c560 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2c570 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2c580 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2c590 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c5a0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2c5b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2c5c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c5d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c5e0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2c5f0 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69  _API double sqli
2c600 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
2c610 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2c620 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2c630 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2c640 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
2c650 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c660 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2c670 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
2c680 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c690 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2c6a0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2c6b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2c6c0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2c6d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c6e0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2c6f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2c700 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2c710 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2c720 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
2c730 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2c740 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2c750 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2c760 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
2c770 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2c780 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
2c790 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
2c7a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2c7b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c7c0 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
2c7d0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
2c7e0 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
2c7f0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
2c800 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c810 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
2c820 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
2c830 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
2c840 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c850 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
2c860 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
2c870 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
2c880 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
2c890 64 20 6e 6f 20 65 72 72 6f 72 73 20 6f 72 0a 2a  d no errors or.*
2c8a0 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
2c8b0 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
2c8c0 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
2c8d0 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
2c8e0 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
2c8f0 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
2c900 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2c910 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2c920 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
2c930 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
2c940 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
2c950 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
2c960 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2c970 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
2c980 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
2c990 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2c9a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2c9b0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2c9c0 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
2c9d0 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
2c9e0 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
2c9f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ca00 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
2ca10 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
2ca20 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
2ca30 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
2ca40 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
2ca50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2ca60 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
2ca70 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
2ca80 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
2ca90 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
2caa0 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
2cab0 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
2cac0 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
2cad0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
2cae0 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
2caf0 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
2cb00 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
2cb10 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
2cb20 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2cb30 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
2cb40 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
2cb50 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
2cb60 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
2cb70 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
2cb80 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
2cb90 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
2cba0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
2cbb0 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
2cbc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cbd0 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2cbe0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
2cbf0 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
2cc00 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2cc10 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2cc20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
2cc30 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
2cc40 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
2cc50 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
2cc60 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
2cc70 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
2cc80 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  rruption..*/.SQL
2cc90 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2cca0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
2ccb0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2ccc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ccd0 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
2cce0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2ccf0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
2cd00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
2cd10 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2cd20 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
2cd30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cd40 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
2cd50 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2cd60 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
2cd70 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
2cd80 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
2cd90 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
2cda0 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
2cdb0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
2cdc0 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
2cdd0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2cde0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2cdf0 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
2ce00 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
2ce10 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
2ce20 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
2ce30 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
2ce40 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
2ce50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2ce60 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
2ce70 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
2ce80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
2ce90 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
2cea0 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
2ceb0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
2cec0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2ced0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2cee0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2cef0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2cf00 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
2cf10 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2cf20 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
2cf30 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
2cf40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2cf50 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
2cf60 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
2cf70 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
2cf80 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2cf90 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2cfa0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
2cfb0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2cfc0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2cfd0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2cfe0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2cff0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
2d000 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
2d010 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
2d020 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2d030 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2d040 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
2d050 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
2d060 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2d070 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
2d080 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
2d090 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
2d0a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
2d0b0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
2d0c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d0d0 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nt] S..*/.SQLITE
2d0e0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2d0f0 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
2d100 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2d110 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
2d120 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
2d130 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
2d140 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
2d150 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
2d160 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
2d170 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
2d180 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2d190 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
2d1a0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
2d1b0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2d1c0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
2d1d0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2d1e0 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
2d1f0 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
2d200 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2d210 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
2d220 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
2d230 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2d240 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
2d250 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
2d260 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
2d270 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2d280 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
2d290 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
2d2a0 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
2d2b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2d2c0 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
2d2d0 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
2d2e0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
2d2f0 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
2d300 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
2d310 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
2d320 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
2d330 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
2d340 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
2d350 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
2d360 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2d370 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
2d380 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
2d390 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2d3a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2d3b0 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
2d3c0 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
2d3d0 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
2d3e0 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
2d3f0 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
2d400 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
2d410 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
2d420 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
2d430 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2d440 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
2d450 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
2d460 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2d470 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
2d480 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
2d490 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2d4a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2d4b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
2d4c0 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
2d4d0 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
2d4e0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
2d4f0 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
2d500 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
2d510 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
2d520 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
2d530 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
2d540 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
2d550 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
2d560 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
2d570 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
2d580 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
2d590 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
2d5a0 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
2d5b0 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
2d5c0 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
2d5d0 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
2d5e0 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
2d5f0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2d600 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
2d610 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
2d620 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
2d630 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
2d640 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2d650 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
2d660 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2d670 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
2d680 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
2d690 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
2d6a0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2d6b0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
2d6c0 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
2d6d0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2d6e0 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
2d6f0 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
2d700 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
2d710 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
2d720 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
2d730 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
2d740 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
2d750 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
2d760 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
2d770 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2d780 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
2d790 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
2d7a0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
2d7b0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
2d7c0 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
2d7d0 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
2d7e0 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
2d7f0 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
2d800 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
2d810 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79  rameters.  Every
2d820 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
2d830 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
2d840 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72  t be able to wor
2d850 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c  k.** with UTF-8,
2d860 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
2d870 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
2d880 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2d890 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
2d8a0 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
2d8b0 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
2d8c0 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20  n another.  ^An 
2d8d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a  application may.
2d8e0 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
2d8f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2d900 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
2d910 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2d920 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
2d930 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
2d940 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
2d950 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
2d960 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
2d970 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  p..** ^When mult
2d980 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2d990 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2d9a0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
2d9b0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
2d9c0 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
2d9d0 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
2d9e0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
2d9f0 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
2da00 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  ersion..** If th
2da10 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69  ere is only a si
2da20 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ngle implementat
2da30 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e  ion which does n
2da40 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78  ot care what tex
2da50 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73  t.** encoding is
2da60 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
2da70 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
2da80 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54  should be [SQLIT
2da90 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  E_ANY]..**.** ^(
2daa0 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
2dab0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
2dac0 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
2dad0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2dae0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
2daf0 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
2db00 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
2db10 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
2db20 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
2db30 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
2db40 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
2db50 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
2db60 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
2db70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
2db80 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
2db90 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
2dba0 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
2dbb0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2dbc0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2dbd0 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
2dbe0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
2dbf0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
2dc00 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
2dc10 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
2dc20 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
2dc30 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
2dc40 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
2dc50 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
2dc60 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
2dc70 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2dc80 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
2dc90 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2dca0 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
2dcb0 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
2dcc0 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
2dcd0 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
2dce0 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
2dcf0 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
2dd00 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2dd10 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
2dd20 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
2dd30 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
2dd40 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
2dd50 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
2dd60 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
2dd70 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
2dd80 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
2dd90 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
2dda0 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
2ddb0 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
2ddc0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
2ddd0 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
2dde0 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
2ddf0 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
2de00 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
2de10 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
2de20 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
2de30 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
2de40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2de50 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
2de60 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
2de70 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
2de80 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
2de90 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2dea0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
2deb0 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
2dec0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
2ded0 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
2dee0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
2def0 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
2df00 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
2df10 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
2df20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
2df30 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2df40 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
2df50 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
2df60 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2df70 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2df80 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
2df90 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
2dfa0 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
2dfb0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2dfc0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2dfd0 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
2dfe0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2dff0 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
2e000 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
2e010 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
2e020 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
2e030 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
2e040 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
2e050 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
2e060 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
2e070 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
2e080 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
2e090 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
2e0a0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
2e0b0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
2e0c0 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
2e0d0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
2e0e0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
2e0f0 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
2e100 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
2e110 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
2e120 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2e130 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
2e140 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
2e150 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2e160 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2e170 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
2e180 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
2e190 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
2e1a0 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
2e1b0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
2e1c0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2e1d0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
2e1e0 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
2e1f0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
2e200 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
2e210 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
2e220 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
2e230 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
2e240 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
2e250 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
2e260 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
2e270 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
2e280 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
2e290 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
2e2a0 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
2e2b0 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
2e2c0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
2e2d0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
2e2e0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
2e2f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2e300 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
2e310 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
2e320 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
2e330 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
2e340 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
2e350 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
2e360 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2e370 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
2e380 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
2e390 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
2e3a0 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
2e3b0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
2e3c0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
2e3d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2e3e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2e3f0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
2e400 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
2e410 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2e420 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2e430 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2e440 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2e450 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2e460 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2e470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2e480 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2e490 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2e4a0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2e4b0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2e4c0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2e4d0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53  3_context*).);.S
2e4e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2e4f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2e500 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
2e510 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2e520 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
2e530 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2e540 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2e550 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2e560 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2e570 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2e580 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2e590 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2e5a0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2e5b0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2e5c0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2e5d0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2e5e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
2e5f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e600 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2e610 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
2e620 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
2e630 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
2e640 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
2e650 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
2e660 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
2e670 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
2e680 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2e690 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2e6a0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2e6b0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
2e6c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2e6d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2e6e0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
2e6f0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
2e700 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
2e710 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
2e720 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e730 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
2e740 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
2e750 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
2e760 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
2e770 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
2e780 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
2e790 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
2e7a0 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
2e7b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e7c0 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
2e7d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e7e0 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
2e7f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e800 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
2e810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e820 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
2e830 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
2e840 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
2e850 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
2e860 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
2e870 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
2e880 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e  eate_function on
2e890 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
2e8a0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
2e8b0 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
2e8c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2e8d0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
2e8e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2e8f0 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
2e900 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
2e910 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
2e920 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
2e930 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
2e940 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
2e950 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
2e960 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
2e970 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
2e980 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
2e990 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
2e9a0 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
2e9b0 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
2e9c0 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
2e9d0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
2e9e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
2e9f0 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
2ea00 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
2ea10 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
2ea20 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
2ea30 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
2ea40 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74   tell you what t
2ea50 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
2ea60 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
2ea70 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
2ea80 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
2ea90 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2eaa0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
2eab0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
2eac0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
2ead0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
2eae0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
2eaf0 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
2eb00 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
2eb10 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
2eb20 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2eb30 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
2eb40 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2eb50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
2eb60 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
2eb70 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2eb80 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
2eb90 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
2eba0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
2ebb0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
2ebc0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
2ebd0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
2ebe0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
2ebf0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2ec00 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
2ec10 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
2ec20 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2ec30 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c  4,int),void*,sql
2ec40 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
2ec50 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2ec60 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
2ec70 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
2ec80 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
2ec90 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
2eca0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2ecb0 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
2ecc0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
2ecd0 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
2ece0 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
2ecf0 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
2ed00 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
2ed10 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
2ed20 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2ed30 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
2ed40 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
2ed50 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
2ed60 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
2ed70 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
2ed80 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
2ed90 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2eda0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
2edb0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2edc0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
2edd0 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
2ede0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
2edf0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
2ee00 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
2ee10 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
2ee20 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
2ee30 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
2ee40 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
2ee50 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
2ee60 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2ee70 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
2ee80 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
2ee90 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
2eea0 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
2eeb0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
2eec0 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
2eed0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
2eee0 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
2eef0 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
2ef00 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2ef10 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
2ef20 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
2ef30 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
2ef40 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2ef50 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
2ef60 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
2ef70 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
2ef80 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
2ef90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2efa0 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
2efb0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
2efc0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
2efd0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2efe0 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
2eff0 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
2f000 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
2f010 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
2f020 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
2f030 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
2f040 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
2f050 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2f060 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
2f070 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
2f080 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
2f090 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
2f0a0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
2f0b0 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
2f0c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2f0d0 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
2f0e0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
2f0f0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
2f100 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
2f110 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
2f120 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
2f130 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
2f140 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
2f150 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
2f160 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
2f170 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
2f180 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
2f190 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
2f1a0 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
2f1b0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
2f1c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
2f1d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
2f1e0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
2f1f0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
2f200 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
2f210 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
2f220 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
2f230 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
2f240 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
2f250 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
2f260 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
2f270 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
2f280 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
2f290 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
2f2a0 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
2f2b0 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
2f2c0 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
2f2d0 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
2f2e0 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
2f2f0 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
2f300 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
2f310 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
2f320 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
2f330 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
2f340 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
2f350 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
2f360 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
2f370 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
2f380 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
2f390 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
2f3a0 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
2f3b0 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
2f3c0 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
2f3d0 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
2f3e0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
2f3f0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
2f400 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2f410 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
2f420 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2f430 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
2f440 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
2f450 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
2f460 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2f470 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
2f480 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2f490 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
2f4a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2f4b0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
2f4c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2f4d0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
2f4e0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
2f4f0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2f500 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
2f510 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
2f520 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
2f530 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
2f540 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
2f550 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
2f560 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2f570 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
2f580 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f590 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2f5a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2f5b0 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
2f5c0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
2f5d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2f5e0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
2f5f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2f600 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c  E_API double sql
2f610 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
2f620 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2f630 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2f640 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2f650 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
2f660 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
2f670 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2f680 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
2f690 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
2f6a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2f6b0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
2f6c0 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
2f6d0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
2f6e0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
2f6f0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2f700 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2f710 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2f720 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
2f730 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2f740 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2f750 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2f760 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2f770 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2f780 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
2f790 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2f7a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2f7b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2f7c0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2f7d0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
2f7e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2f7f0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
2f800 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2f810 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f820 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
2f830 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
2f840 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
2f850 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
2f860 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2f870 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
2f880 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
2f890 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
2f8a0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
2f8b0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
2f8c0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
2f8d0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2f8e0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
2f8f0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
2f900 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
2f910 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
2f920 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
2f930 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
2f940 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
2f950 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
2f960 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2f970 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
2f980 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
2f990 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
2f9a0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
2f9b0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
2f9c0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
2f9d0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
2f9e0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
2f9f0 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
2fa00 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
2fa10 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
2fa20 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2fa30 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
2fa40 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
2fa50 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
2fa60 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
2fa70 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
2fa80 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
2fa90 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
2faa0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
2fab0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
2fac0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
2fad0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
2fae0 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
2faf0 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
2fb00 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
2fb10 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
2fb20 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
2fb30 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
2fb40 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
2fb50 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
2fb60 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
2fb70 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2fb80 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
2fb90 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
2fba0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
2fbb0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
2fbc0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
2fbd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
2fbe0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2fbf0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
2fc00 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
2fc10 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65  er if N is.** le
2fc20 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
2fc30 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
2fc40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
2fc50 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
2fc60 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
2fc70 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
2fc80 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
2fc90 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2fca0 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
2fcb0 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
2fcc0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
2fcd0 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
2fce0 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
2fcf0 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
2fd00 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
2fd10 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
2fd20 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2fd30 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
2fd40 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
2fd50 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
2fd60 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
2fd70 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
2fd80 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  allocation.)^.**
2fd90 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
2fda0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
2fdb0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
2fdc0 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
2fdd0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2fde0 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
2fdf0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
2fe00 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
2fe10 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
2fe20 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
2fe30 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
2fe40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2fe50 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
2fe60 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
2fe70 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
2fe80 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
2fe90 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
2fea0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
2feb0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2fec0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
2fed0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2fee0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
2fef0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2ff00 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2ff10 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2ff20 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2ff30 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2ff40 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
2ff50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
2ff60 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2ff70 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2ff80 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
2ff90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ffa0 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
2ffb0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
2ffc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
2ffd0 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
2ffe0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
2fff0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
30000 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
30010 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
30020 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
30030 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
30040 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
30050 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
30060 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
30070 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
30080 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
30090 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
300a0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
300b0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
300c0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
300d0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
300e0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
300f0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
30100 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
30110 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
30120 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
30130 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
30140 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
30150 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
30160 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
30170 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
30180 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
30190 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
301a0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
301b0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
301c0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
301d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
301e0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
301f0 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
30200 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
30210 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
30220 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
30230 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
30240 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
30250 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
30260 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30270 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
30280 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
30290 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
302a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
302b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
302c0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
302d0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
302e0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
302f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30300 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
30310 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
30320 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
30330 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
30340 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
30350 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
30360 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
30370 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
30380 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
30390 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
303a0 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
303b0 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
303c0 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
303d0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
303e0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
303f0 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
30400 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
30410 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
30420 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
30430 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
30440 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
30450 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
30460 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
30470 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
30480 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
30490 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
304a0 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
304b0 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
304c0 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
304d0 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
304e0 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
304f0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
30500 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
30510 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
30520 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
30530 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
30540 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
30550 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
30560 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
30570 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
30580 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
30590 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
305a0 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
305b0 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
305c0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
305d0 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
305e0 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
305f0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
30600 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
30610 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
30620 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
30630 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
30640 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
30650 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
30660 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
30670 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
30680 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
30690 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
306a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
306b0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
306c0 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
306d0 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
306e0 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
306f0 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
30700 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
30710 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
30720 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
30730 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
30740 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
30750 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
30760 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
30770 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
30780 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
30790 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
307a0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
307b0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
307c0 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
307d0 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
307e0 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
307f0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
30800 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
30810 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
30820 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
30830 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
30840 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
30850 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
30860 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
30870 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
30880 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
30890 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
308a0 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
308b0 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20  * ^If it is not 
308c0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
308d0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
308e0 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
308f0 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
30900 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
30910 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
30920 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
30930 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
30940 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
30950 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
30960 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
30970 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
30980 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
30990 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
309a0 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
309b0 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
309c0 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
309d0 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
309e0 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
309f0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
30a00 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
30a10 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65   any time.  ^The
30a20 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20   only guarantee 
30a30 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64  is that.** the d
30a40 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62  estructor will b
30a50 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
30a60 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
30a70 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  dropped..**.** ^
30a80 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
30a90 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
30aa0 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
30ab0 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
30ac0 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
30ad0 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
30ae0 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
30af0 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
30b00 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
30b10 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
30b20 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].)^.**.** These
30b30 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
30b40 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
30b50 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
30b60 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
30b70 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
30b80 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
30b90 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
30ba0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
30bb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30bc0 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f   int N);.SQLITE_
30bd0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
30be0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
30bf0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
30c00 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
30c10 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
30c20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30c30 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
30c40 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
30c50 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a  ructor Behavior.
30c60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
30c70 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
30c80 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
30c90 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
30ca0 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
30cb0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
30cc0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
30cd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
30ce0 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20  ob()].  ^If the 
30cf0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
30d00 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
30d10 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
30d20 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
30d30 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
30d40 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
30d50 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
30d60 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
30d70 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
30d80 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c  ed.  ^The.** SQL
30d90 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
30da0 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
30db0 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
30dc0 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
30dd0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
30de0 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
30df0 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
30e00 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
30e10 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
30e20 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
30e30 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
30e40 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
30e50 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
30e60 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
30e70 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
30e80 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
30e90 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
30ea0 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
30eb0 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
30ec0 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
30ed0 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
30ee0 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
30ef0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
30f00 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
30f10 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
30f20 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
30f30 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
30f40 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
30f50 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
30f60 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
30f70 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
30f80 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
30f90 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
30fa0 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
30fb0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
30fc0 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
30fd0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
30fe0 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
30ff0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
31000 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
31010 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
31020 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
31030 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
31040 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
31050 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
31060 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
31070 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
31080 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
31090 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
310a0 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
310b0 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
310c0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
310d0 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
310e0 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
310f0 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
31100 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
31110 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
31120 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
31130 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31140 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
31150 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
31160 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
31170 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
31180 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31190 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
311a0 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
311b0 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
311c0 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
311d0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
311e0 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
311f0 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
31200 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
31210 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
31220 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31230 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
31240 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
31250 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
31260 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31270 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
31280 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
31290 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
312a0 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
312b0 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
312c0 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
312d0 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
312e0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
312f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31300 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
31310 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
31320 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
31330 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31340 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
31350 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
31360 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
31370 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
31380 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
31390 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
313a0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
313b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
313c0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
313d0 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
313e0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
313f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
31400 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
31410 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
31420 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
31430 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
31440 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
31450 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
31460 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
31470 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31480 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
31490 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
314a0 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
314b0 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
314c0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
314d0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
314e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
314f0 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
31500 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
31510 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
31520 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
31530 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
31540 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
31550 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
31560 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
31570 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
31580 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31590 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
315a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
315b0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
315c0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
315d0 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
315e0 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
315f0 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
31600 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
31610 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
31620 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
31630 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
31640 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
31650 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
31660 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
31670 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
31680 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
31690 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
316a0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
316b0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
316c0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
316d0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
316e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
316f0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
31700 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31710 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
31720 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
31730 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
31740 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
31750 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
31760 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
31770 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
31780 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
31790 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
317a0 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
317b0 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
317c0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
317d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
317e0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
317f0 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
31800 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
31810 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
31820 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
31830 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
31840 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
31850 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
31860 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
31870 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
31880 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
31890 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
318a0 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
318b0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
318c0 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
318d0 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
318e0 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
318f0 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
31900 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f  lite3_result_too
31910 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
31920 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
31930 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
31940 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
31950 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
31960 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
31970 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
31980 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31990 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20  _result_nomem() 
319a0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
319b0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
319c0 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
319d0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
319e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
319f0 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
31a00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31a10 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
31a20 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
31a30 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
31a40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31a50 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31a60 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
31a70 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
31a80 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
31a90 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
31aa0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
31ab0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
31ac0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
31ad0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
31ae0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
31af0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31b00 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
31b10 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
31b20 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
31b30 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
31b40 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
31b50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31b60 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
31b70 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
31b80 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
31b90 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
31ba0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31bb0 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
31bc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31bd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31be0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
31bf0 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
31c00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31c10 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
31c20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31c30 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
31c40 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
31c50 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
31c60 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31c70 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31c80 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
31c90 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
31ca0 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
31cb0 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
31cc0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
31cd0 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
31ce0 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
31cf0 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
31d00 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
31d10 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
31d20 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
31d30 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
31d40 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
31d50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
31d60 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
31d70 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
31d80 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
31d90 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
31da0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
31db0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
31dc0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
31dd0 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
31de0 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
31df0 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
31e00 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
31e10 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
31e20 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
31e30 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
31e40 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
31e50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31e60 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
31e70 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
31e80 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
31e90 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
31ea0 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
31eb0 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
31ec0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
31ed0 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
31ee0 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
31ef0 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
31f00 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a  nction result..*
31f10 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
31f20 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
31f30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31f40 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
31f50 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
31f60 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
31f70 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
31f80 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
31f90 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
31fa0 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
31fb0 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
31fc0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
31fd0 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
31fe0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
31ff0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
32000 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
32010 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
32020 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
32030 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
32040 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
32050 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
32060 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
32070 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
32080 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
32090 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
320a0 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
320b0 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
320c0 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
320d0 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
320e0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
320f0 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
32100 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
32110 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
32120 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
32130 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
32140 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
32150 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
32160 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
32170 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
32180 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
32190 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
321a0 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
321b0 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
321c0 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
321d0 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
321e0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
321f0 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
32200 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
32210 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
32220 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
32230 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
32240 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32250 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
32260 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
32270 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
32280 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
32290 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
322a0 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
322b0 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
322c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
322d0 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
322e0 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
322f0 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a  ameter.  ^The.**
32300 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32310 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
32320 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
32330 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
32340 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
32350 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
32360 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
32370 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
32380 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
32390 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
323a0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
323b0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
323c0 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
323d0 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63  m..** ^A [protec
323e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
323f0 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
32400 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
32410 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
32420 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32430 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
32440 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
32450 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
32460 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
32470 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
32480 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
32490 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
324a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
324b0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
324c0 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
324d0 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
324e0 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
324f0 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
32500 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32510 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
32520 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
32530 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
32540 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
32550 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
32560 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
32570 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32580 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
32590 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
325a0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
325b0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
325c0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
325d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
325e0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
325f0 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51  xt*, double);.SQ
32600 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
32610 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32620 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
32630 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
32640 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
32650 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
32660 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
32670 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32680 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
32690 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
326a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
326b0 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
326c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
326d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
326e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
326f0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
32700 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
32710 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
32720 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32730 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
32740 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
32750 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
32760 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32770 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
32780 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51  ntext*, int);.SQ
32790 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
327a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
327b0 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
327c0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
327d0 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
327e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
327f0 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
32800 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
32810 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
32820 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
32830 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32840 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
32850 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
32860 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
32870 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32880 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
32890 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
328a0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
328b0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
328c0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
328d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
328e0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
328f0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
32900 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
32910 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
32920 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
32930 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
32940 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
32950 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
32960 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
32970 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
32980 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
32990 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
329a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
329b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
329c0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
329d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
329e0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
329f0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
32a00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32a10 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
32a20 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
32a30 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  s.**.** ^These f
32a40 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65  unctions add, re
32a50 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20  move, or modify 
32a60 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73  a [collation] as
32a70 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
32a80 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
32a90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
32aa0 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
32ab0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
32ac0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
32ad0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  he collation is 
32ae0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
32af0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
32b00 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
32b10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
32b20 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
32b30 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
32b40 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
32b50 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
32b60 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
32b70 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
32b80 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e  .** ^Collation n
32b90 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72  ames that compar
32ba0 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e  e equal accordin
32bb0 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  g to [sqlite3_st
32bc0 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a  rnicmp()] are.**
32bd0 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62   considered to b
32be0 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  e the same name.
32bf0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69  .**.** ^(The thi
32c00 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65  rd argument (eTe
32c10 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f  xtRep) must be o
32c20 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
32c30 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  nts:.** <ul>.** 
32c40 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
32c50 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8],.** <li> [SQL
32c60 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a  ITE_UTF16LE],.**
32c70 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
32c80 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16BE],.** <li> 
32c90 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
32ca0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
32cb0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
32cc0 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  ]..** </ul>)^.**
32cd0 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61   ^The eTextRep a
32ce0 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e  rgument determin
32cf0 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  es the encoding 
32d00 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65  of strings passe
32d10 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c  d.** to the coll
32d20 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
32d30 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61  allback, xCallba
32d40 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  ck..** ^The [SQL
32d50 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b  ITE_UTF16] and [
32d60 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
32d70 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72  GNED] values for
32d80 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72   eTextRep.** for
32d90 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  ce strings to be
32da0 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69   UTF16 with nati
32db0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
32dc0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
32dd0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
32de0 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70  lue for eTextRep
32df0 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20   forces strings 
32e00 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61  to begin.** on a
32e10 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72  n even byte addr
32e20 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ess..**.** ^The 
32e30 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
32e40 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70   pArg, is an app
32e50 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
32e60 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61  inter that is pa
32e70 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20  ssed.** through 
32e80 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
32e90 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c  ument to the col
32ea0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
32eb0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
32ec0 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
32ed0 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20  ent, xCallback, 
32ee0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
32ef0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
32f00 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74  nction..** ^Mult
32f10 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  iple collating f
32f20 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20  unctions can be 
32f30 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
32f40 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
32f50 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65  ut.** with diffe
32f60 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61  rent eTextRep pa
32f70 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c  rameters and SQL
32f80 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69  ite will use whi
32f90 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69  chever.** functi
32fa0 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20  on requires the 
32fb0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
32fc0 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74  data transformat
32fd0 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
32fe0 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65  xCallback argume
32ff0 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  nt is NULL then 
33000 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
33010 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c  nction is.** del
33020 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c  eted.  ^When all
33030 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
33040 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20  ions having the 
33050 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65  same name are de
33060 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63  leted,.** that c
33070 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c  ollation is no l
33080 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a  onger usable..**
33090 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69  .** ^The collati
330a0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
330b0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
330c0 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74  with a copy of t
330d0 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c  he pArg .** appl
330e0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
330f0 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77  nter and with tw
33100 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65  o strings in the
33110 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66   encoding specif
33120 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54  ied.** by the eT
33130 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e  extRep argument.
33140 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20    The collating 
33150 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65  function must re
33160 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  turn an.** integ
33170 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74  er that is negat
33180 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f  ive, zero, or po
33190 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65  sitive.** if the
331a0 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
331b0 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61   less than, equa
331c0 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
331d0 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
331e0 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ,.** respectivel
331f0 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  y.  A collating 
33200 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c  function must al
33210 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
33220 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67  same answer.** g
33230 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e  iven the same in
33240 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72  puts.  If two or
33250 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20   more collating 
33260 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65  functions are re
33270 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74  gistered.** to t
33280 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f  he same collatio
33290 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69  n name (using di
332a0 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
332b0 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c   values) then al
332c0 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61  l.** must give a
332d0 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73  n equivalent ans
332e0 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64  wer when invoked
332f0 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74   with equivalent
33300 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
33310 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
33320 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68  ion must obey th
33330 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70  e following prop
33340 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a  erties for all.*
33350 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20  * strings A, B, 
33360 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c  and C:.**.** <ol
33370 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  >.** <li> If A==
33380 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20  B then B==A..** 
33390 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64  <li> If A==B and
333a0 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e   B==C then A==C.
333b0 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
333c0 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a  ;B THEN B&gt;A..
333d0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b  ** <li> If A&lt;
333e0 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65  B and B&lt;C the
333f0 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f  n A&lt;C..** </o
33400 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f  l>.**.** If a co
33410 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33420 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68   fails any of th
33430 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69  e above constrai
33440 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20  nts and that.** 
33450 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
33460 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65  on is  registere
33470 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e  d and used, then
33480 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
33490 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e   SQLite.** is un
334a0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
334b0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
334c0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
334d0 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
334e0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
334f0 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20  ation().** with 
33500 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61  the addition tha
33510 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63  t the xDestroy c
33520 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
33530 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a  ed on pArg when.
33540 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** the collating
33550 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
33560 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  eted..** ^Collat
33570 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
33580 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  e deleted when t
33590 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64  hey are overridd
335a0 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63  en by later.** c
335b0 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c  alls to the coll
335c0 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66  ation creation f
335d0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e  unctions or when
335e0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
335f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
33600 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73   closed using [s
33610 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
33620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73  .**.** ^The xDes
33630 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
33640 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c   <u>not</u> call
33650 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71  ed if the .** sq
33660 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33670 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63  lation_v2() func
33680 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70  tion fails.  App
33690 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69  lications that i
336a0 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
336b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
336c0 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f  n_v2() with a no
336d0 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20  n-NULL xDestroy 
336e0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
336f0 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65  .** check the re
33700 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69  turn code and di
33710 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70  spose of the app
33720 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
33730 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c  inter.** themsel
33740 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20  ves rather than 
33750 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65  expecting SQLite
33760 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74   to deal with it
33770 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68   for them..** Th
33780 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20  is is different 
33790 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72  from every other
337a0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
337b0 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73  e.  The inconsis
337c0 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66  tency .** is unf
337d0 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e  ortunate but can
337e0 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77  not be changed w
337f0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
33800 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f  backwards .** co
33810 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
33820 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73  ** See also:  [s
33830 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
33840 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b  _needed()] and [
33850 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33860 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a  n_needed16()]..*
33870 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
33880 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33890 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
338a0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
338b0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
338c0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
338d0 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
338e0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
338f0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
33900 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
33910 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  id*).);.SQLITE_A
33920 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
33930 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
33940 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
33950 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
33960 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
33970 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
33980 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
33990 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
339a0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
339b0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20  ,const void*),. 
339c0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
339d0 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54  (void*).);.SQLIT
339e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
339f0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33a00 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
33a10 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
33a20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
33a30 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
33a40 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
33a50 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
33a60 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
33a70 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
33a80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33a90 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
33aa0 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ded Callbacks.**
33ab0 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61  .** ^To avoid ha
33ac0 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
33ad0 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
33ae0 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
33af0 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
33b00 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
33b10 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
33b20 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
33b30 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
33b40 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
33b50 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
33b60 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
33b70 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
33b80 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
33b90 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e  nce is required.
33ba0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
33bb0 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
33bc0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
33bd0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33be0 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
33bf0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
33c00 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
33c10 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
33c20 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
33c30 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
33c40 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
33c50 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ^If sqlite3_coll
33c60 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
33c70 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
33c80 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
33c90 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
33ca0 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
33cb0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20  te order..** ^A 
33cc0 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
33cd0 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
33ce0 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f   the existing co
33cf0 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63  llation-needed c
33d00 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
33d10 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  (When the callba
33d20 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
33d30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
33d40 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
33d50 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
33d60 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
33d70 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33d80 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
33d90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
33da0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
33db0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
33dc0 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
33dd0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
33de0 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
33df0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
33e00 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
33e10 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
33e20 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
33e30 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
33e40 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
33e50 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
33e60 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
33e70 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
33e80 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
33e90 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
33ea0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
33eb0 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
33ec0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
33ed0 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ence.)^.**.** Th
33ee0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
33ef0 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
33f00 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
33f10 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
33f20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
33f30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
33f40 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33f50 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
33f60 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
33f70 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33f80 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  _v2()]..*/.SQLIT
33f90 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
33fa0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
33fb0 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
33fc0 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
33fd0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
33fe0 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
33ff0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
34000 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
34010 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
34020 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71  n_needed16(.  sq
34030 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
34040 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ,.  void(*)(void
34050 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
34060 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f  TextRep,const vo
34070 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20  id*).);..#ifdef 
34080 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43  SQLITE_HAS_CODEC
34090 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
340a0 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e  he key for an en
340b0 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65  crypted database
340c0 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
340d0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c  should be.** cal
340e0 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20  led right after 
340f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
34100 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
34110 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
34120 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
34130 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
34140 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
34150 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
34160 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
34170 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
34180 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
34190 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
341a0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
341b0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
341c0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
341d0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
341e0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
341f0 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
34200 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
34210 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
34220 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
34230 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
34240 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
34250 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
34260 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
34270 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
34280 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
34290 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
342a0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
342b0 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
342c0 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
342d0 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
342e0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
342f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
34300 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28  t sqlite3_rekey(
34310 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
34320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34330 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
34340 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
34350 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
34360 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
34370 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a  /* The new key *
34380 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  /.);../*.** Spec
34390 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
343a0 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45  on key for a SEE
343b0 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
343c0 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
343d0 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45  , none of the SE
343e0 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  E routines will 
343f0 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  work..*/.SQLITE_
34400 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
34410 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20  _activate_see(. 
34420 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
34430 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
34440 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
34450 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
34460 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  f..#ifdef SQLITE
34470 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a  _ENABLE_CEROD./*
34480 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
34490 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
344a0 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62  or a CEROD datab
344b0 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
344c0 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
344d0 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f   of the CEROD ro
344e0 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
344f0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
34500 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
34510 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63  ivate_cerod(.  c
34520 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
34530 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
34540 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
34550 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
34560 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34570 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
34580 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
34590 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ime.**.** The sq
345a0 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75  lite3_sleep() fu
345b0 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68  nction causes th
345c0 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
345d0 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
345e0 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
345f0 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
34600 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
34610 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
34620 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
34630 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   If the operatin
34640 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
34650 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
34660 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a  requests with.**
34670 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d   millisecond tim
34680 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68  e resolution, th
34690 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c  en the time will
346a0 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74   be rounded up t
346b0 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74  o.** the nearest
346c0 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d   second. The num
346d0 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
346e0 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
346f0 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74  ually.** request
34700 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
34710 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
34720 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
34730 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e  ^SQLite implemen
34740 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
34750 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
34760 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
34770 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
34780 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
34790 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65   object.  If the
347a0 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
347b0 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75  .** of the defau
347c0 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d  lt VFS is not im
347d0 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63  plemented correc
347e0 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c  tly, or not impl
347f0 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c  emented at.** al
34800 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  l, then the beha
34810 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
34820 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 69  sleep() may devi
34830 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73  ate from the des
34840 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74  cription.** in t
34850 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
34860 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49 54  graphs..*/.SQLIT
34870 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
34880 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
34890 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
348a0 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
348b0 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
348c0 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
348d0 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
348e0 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
348f0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
34900 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
34910 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
34920 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
34930 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
34940 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
34950 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
34960 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  by SQLite when u
34970 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
34980 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
34990 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70  FS].** will be p
349a0 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
349b0 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20  rectory.)^  ^If 
349c0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
349d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
349e0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
349f0 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
34a00 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
34a10 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
34a20 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
34a30 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
34a40 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
34a50 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
34a60 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
34a70 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
34a80 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
34a90 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
34aa0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
34ab0 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
34ac0 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
34ad0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
34ae0 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
34af0 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
34b00 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
34b10 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
34b20 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
34b30 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
34b40 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
34b50 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
34b60 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
34b70 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
34b80 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
34b90 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
34ba0 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
34bb0 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
34bc0 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
34bd0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
34be0 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74  ** ^The [temp_st
34bf0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
34c00 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
34c10 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
34c20 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
34c30 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
34c40 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
34c50 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
34c60 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
34c70 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74  .** the [temp_st
34c80 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
34c90 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
34ca0 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
34cb0 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
34cc0 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
34cd0 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
34ce0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
34cf0 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
34d00 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
34d10 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
34d20 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
34d30 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
34d40 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
34d50 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
34d60 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
34d70 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
34d80 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
34d90 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
34da0 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
34db0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
34dc0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
34dd0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
34de0 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
34df0 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74   of the [temp_st
34e00 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
34e10 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
34e20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
34e30 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
34e40 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
34e50 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ory;../*.** CAPI
34e60 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41  3REF: Test For A
34e70 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a  uto-Commit Mode.
34e80 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75  ** KEYWORDS: {au
34e90 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a  tocommit mode}.*
34ea0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34eb0 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
34ec0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
34ed0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
34ee0 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
34ef0 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
34f00 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
34f10 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
34f20 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
34f30 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75  spectively.  ^Au
34f40 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
34f50 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a   on by default..
34f60 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  ** ^Autocommit m
34f70 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
34f80 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61  by a [BEGIN] sta
34f90 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f  tement..** ^Auto
34fa0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72  commit mode is r
34fb0 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b  e-enabled by a [
34fc0 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c  COMMIT] or [ROLL
34fd0 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  BACK]..**.** If 
34fe0 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66  certain kinds of
34ff0 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e   errors occur on
35000 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74   a statement wit
35010 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74  hin a multi-stat
35020 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63  ement.** transac
35030 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63  tion (errors inc
35040 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  luding [SQLITE_F
35050 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f  ULL], [SQLITE_IO
35060 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ERR],.** [SQLITE
35070 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45  _NOMEM], [SQLITE
35080 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c  _BUSY], and [SQL
35090 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20  ITE_INTERRUPT]) 
350a0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e  then the.** tran
350b0 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  saction might be
350c0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
350d0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
350e0 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20   only way to.** 
350f0 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72  find out whether
35100 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
35110 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
35120 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
35130 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72  n after.** an er
35140 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68  ror is to use th
35150 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
35160 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  ** If another th
35170 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65  read changes the
35180 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74   autocommit stat
35190 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  us of the databa
351a0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
351b0 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74   while this rout
351c0 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20  ine is running, 
351d0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
351e0 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65  value.** is unde
351f0 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  fined..*/.SQLITE
35200 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
35210 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
35220 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
35230 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
35240 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61   The Database Ha
35250 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72  ndle Of A Prepar
35260 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
35270 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35280 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66  db_handle interf
35290 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
352a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
352b0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
352c0 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70  to which a [prep
352d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
352e0 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b  belongs.  ^The [
352f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35300 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ion].** returned
35310 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68   by sqlite3_db_h
35320 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d  andle is the sam
35330 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
35340 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20  ection].** that 
35350 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72  was the first ar
35360 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
35370 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
35380 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72  e_v2()] call (or
35390 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74   its variants) t
353a0 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a  hat was used to.
353b0 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74  ** create the st
353c0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66  atement in the f
353d0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 53  irst place..*/.S
353e0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
353f0 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
35400 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
35410 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
35420 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
35430 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
35440 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
35450 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
35460 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
35470 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
35480 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
35490 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
354a0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
354b0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
354c0 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
354d0 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
354e0 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
354f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35500 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
35510 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
35520 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
35530 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
35540 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35550 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
35560 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
35570 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
35580 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
35590 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
355a0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  , it returns NUL
355b0 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61  L..**.** The [da
355c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
355d0 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20  n] pointer D in 
355e0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
355f0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
35600 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72  D,S)] must refer
35610 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   to an open data
35620 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
35630 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63  on and in partic
35640 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65  ular must not be
35650 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
35660 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  .*/.SQLITE_API s
35670 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c  qlite3_stmt *sql
35680 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73  ite3_next_stmt(s
35690 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c  qlite3 *pDb, sql
356a0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
356b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
356c0 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
356d0 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
356e0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
356f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35700 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
35710 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
35720 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
35730 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
35740 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
35750 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
35760 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d  is [COMMIT | com
35770 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79  mitted]..** ^Any
35780 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
35790 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
357a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
357b0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
357c0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
357d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
357e0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
357f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c  ^The sqlite3_rol
35800 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
35810 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
35820 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
35830 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
35840 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
35850 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
35860 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c  [ROLLBACK | roll
35870 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e  ed back]..** ^An
35880 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
35890 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
358a0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c  l to sqlite3_rol
358b0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  lback_hook().** 
358c0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
358d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
358e0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
358f0 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67  ** ^The pArg arg
35900 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
35910 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
35920 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20  allback..** ^If 
35930 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
35940 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
35950 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
35960 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  on-zero,.** then
35970 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
35980 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
35990 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
359a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
359b0 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  mit_hook(D,C,P) 
359c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  and sqlite3_roll
359d0 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  back_hook(D,C,P)
359e0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
359f0 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d  turn the P argum
35a00 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
35a10 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68  vious call of th
35a20 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
35a30 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
35a40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35a50 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
35a60 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
35a70 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66   call for each f
35a80 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a  unction on D..**
35a90 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
35aa0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35ab0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
35ac0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
35ad0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
35ae0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35af0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
35b00 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79  e callback.  Any
35b10 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
35b20 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
35b30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
35b40 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
35b50 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
35b60 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
35b70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
35b80 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
35b90 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d  riggered the com
35ba0 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61  mit.** or rollba
35bb0 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66  ck hook in the f
35bc0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e  irst place..** N
35bd0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
35be0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
35bf0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
35c00 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
35c10 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
35c20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
35c30 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
35c40 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
35c50 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
35c60 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67  .** ^Registering
35c70 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
35c80 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
35c90 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57  llback..**.** ^W
35ca0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
35cb0 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  ook callback rou
35cc0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
35cd0 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a  o, the [COMMIT].
35ce0 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  ** operation is 
35cf0 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69  allowed to conti
35d00 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e  nue normally.  ^
35d10 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  If the commit ho
35d20 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f  ok.** returns no
35d30 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
35d40 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e   [COMMIT] is con
35d50 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52  verted into a [R
35d60 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68  OLLBACK]..** ^Th
35d70 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  e rollback hook 
35d80 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20  is invoked on a 
35d90 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65  rollback that re
35da0 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d  sults from a com
35db0 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75  mit.** hook retu
35dc0 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  rning non-zero, 
35dd0 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64  just as it would
35de0 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68   be with any oth
35df0 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  er rollback..**.
35e00 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
35e10 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
35e20 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
35e30 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
35e40 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  been.** rolled b
35e50 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
35e60 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
35e70 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
35e80 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
35e90 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
35ea0 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
35eb0 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
35ec0 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20   occur..** ^The 
35ed0 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
35ee0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
35ef0 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
35f00 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  n is.** automati
35f10 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
35f20 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61  k because the da
35f30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35f40 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
35f50 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
35f60 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
35f70 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63  hook()] interfac
35f80 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
35f90 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
35fa0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74  ommit_hook(sqlit
35fb0 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
35fc0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
35fd0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
35fe0 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
35ff0 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ok(sqlite3*, voi
36000 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f  d(*)(void *), vo
36010 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
36020 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e  I3REF: Data Chan
36030 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ge Notification 
36040 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
36050 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64  ^The sqlite3_upd
36060 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ate_hook() inter
36070 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
36080 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
36090 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
360a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
360b0 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20  ion] identified 
360c0 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
360d0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69  ument.** to be i
360e0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
360f0 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  a row is updated
36100 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
36110 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63  leted..** ^Any c
36120 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
36130 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
36140 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  o this function.
36150 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
36160 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36170 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
36180 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  n..**.** ^The se
36190 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
361a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
361b0 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e  e function to in
361c0 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72  voke when a.** r
361d0 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
361e0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
361f0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ed..** ^The firs
36200 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
36210 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  e callback is a 
36220 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
36230 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  d argument.** to
36240 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
36250 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20  hook()..** ^The 
36260 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20  second callback 
36270 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
36280 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52  of [SQLITE_INSER
36290 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45  T], [SQLITE_DELE
362a0 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  TE],.** or [SQLI
362b0 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65  TE_UPDATE], depe
362c0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65  nding on the ope
362d0 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73  ration that caus
362e0 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  ed the callback.
362f0 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
36300 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  ..** ^The third 
36310 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d  and fourth argum
36320 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ents to the call
36330 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69  back contain poi
36340 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20  nters to the.** 
36350 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62  database and tab
36360 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69  le name containi
36370 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20  ng the affected 
36380 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e  row..** ^The fin
36390 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61  al callback para
363a0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f  meter is the [ro
363b0 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e  wid] of the row.
363c0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65  .** ^In the case
363d0 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74   of an update, t
363e0 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69  his is the [rowi
363f0 64 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64  d] after the upd
36400 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e  ate takes place.
36410 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64  .**.** ^(The upd
36420 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20  ate hook is not 
36430 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74  invoked when int
36440 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62  ernal system tab
36450 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66  les are.** modif
36460 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65  ied (i.e. sqlite
36470 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69  _master and sqli
36480 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a  te_sequence).)^.
36490 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75  **.** ^In the cu
364a0 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
364b0 74 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65  tion, the update
364c0 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20   hook.** is not 
364d0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70  invoked when dup
364e0 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72  lication rows ar
364f0 65 20 64 65 6c 65 74 65 64 20 62 65 63 61 75 73  e deleted becaus
36500 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43  e of an.** [ON C
36510 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e  ONFLICT | ON CON
36520 46 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63  FLICT REPLACE] c
36530 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20  lause.  ^Nor is 
36540 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
36550 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ** invoked when 
36560 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
36570 20 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e   using the [trun
36580 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
36590 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70  n]..** The excep
365a0 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e  tions defined in
365b0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 20   this paragraph 
365c0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
365d0 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65  a future.** rele
365e0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
365f0 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20  *.** The update 
36600 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74  hook implementat
36610 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ion must not do 
36620 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
36630 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
36640 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36650 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
36660 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  d the update hoo
36670 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a  k.  Any actions.
36680 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ** to modify the
36690 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
366a0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66  tion must be def
366b0 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65  erred until afte
366c0 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  r the.** complet
366d0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
366e0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
366f0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
36700 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e  the update hook.
36710 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
36720 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
36730 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
36740 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
36750 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
36760 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36770 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
36780 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
36790 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
367a0 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  h..**.** ^The sq
367b0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
367c0 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f  k(D,C,P) functio
367d0 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  n.** returns the
367e0 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d   P argument from
367f0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
36800 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d  ll.** on the sam
36810 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
36820 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55  ection] D, or NU
36830 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69  LL for.** the fi
36840 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a  rst call on D..*
36850 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
36860 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  e [sqlite3_commi
36870 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73  t_hook()] and [s
36880 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
36890 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  hook()].** inter
368a0 66 61 63 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  faces..*/.SQLITE
368b0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
368c0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a  e3_update_hook(.
368d0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
368e0 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e  oid(*)(void *,in
368f0 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c  t ,char const *,
36900 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c  char const *,sql
36910 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76  ite3_int64),.  v
36920 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  oid*.);../*.** C
36930 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
36940 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65  Or Disable Share
36950 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a  d Pager Cache.**
36960 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72   KEYWORDS: {shar
36970 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20  ed cache}.**.** 
36980 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65  ^(This routine e
36990 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
369a0 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f  es the sharing o
369b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
369c0 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65  ache.** and sche
369d0 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ma data structur
369e0 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61  es between [data
369f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
36a00 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a  | connections].*
36a10 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  * to the same da
36a20 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20  tabase. Sharing 
36a30 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
36a40 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72  e argument is tr
36a50 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c  ue.** and disabl
36a60 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
36a70 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a  nt is false.)^.*
36a80 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72  *.** ^Cache shar
36a90 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61  ing is enabled a
36aa0 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20  nd disabled for 
36ab0 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73  an entire proces
36ac0 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  s..** This is a 
36ad0 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c  change as of SQL
36ae0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
36af0 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73  0. In prior vers
36b00 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a  ions of SQLite,.
36b10 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65  ** sharing was e
36b20 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
36b30 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65  ed for each thre
36b40 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  ad separately..*
36b50 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65  *.** ^(The cache
36b60 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65   sharing mode se
36b70 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  t by this interf
36b80 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20  ace effects all 
36b90 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  subsequent.** ca
36ba0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
36bb0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
36bc0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
36bd0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
36be0 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  6()]..** Existin
36bf0 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  g database conne
36c00 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
36c10 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20  use the sharing 
36c20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73  mode.** that was
36c30 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68   in effect at th
36c40 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65  e time they were
36c50 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a   opened.)^.**.**
36c60 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
36c70 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
36c80 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61  OK] if shared ca
36c90 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20  che was enabled 
36ca0 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73  or disabled.** s
36cb0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e  uccessfully.  An
36cc0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
36cd0 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77   returned otherw
36ce0 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68  ise.)^.**.** ^Sh
36cf0 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
36d00 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
36d10 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68  t. But this migh
36d20 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66  t change in.** f
36d30 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
36d40 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69  f SQLite.  Appli
36d50 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72  cations that car
36d60 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a  e about shared.*
36d70 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20  * cache setting 
36d80 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78  should set it ex
36d90 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20  plicitly..**.** 
36da0 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69  See Also:  [SQLi
36db0 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20  te Shared-Cache 
36dc0 4d 6f 64 65 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Mode].*/.SQLITE_
36dd0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
36de0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
36df0 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  che(int);../*.**
36e00 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d   CAPI3REF: Attem
36e10 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20  pt To Free Heap 
36e20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  Memory.**.** ^Th
36e30 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  e sqlite3_releas
36e40 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72  e_memory() inter
36e50 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
36e60 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a   free N bytes.**
36e70 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
36e80 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20  by deallocating 
36e90 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
36ea0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
36eb0 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20  .** held by the 
36ec0 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79  database library
36ed0 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20  .   Memory used 
36ee0 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73  to cache databas
36ef0 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d  e.** pages to im
36f00 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
36f10 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  e is an example 
36f20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  of non-essential
36f30 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c   memory..** ^sql
36f40 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
36f50 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68  ory() returns th
36f60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
36f70 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64  s actually freed
36f80 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74  ,.** which might
36f90 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73   be more or less
36fa0 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74   than the amount
36fb0 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e   requested..** ^
36fc0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  The sqlite3_rele
36fd0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75  ase_memory() rou
36fe0 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20  tine is a no-op 
36ff0 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a  returning zero.*
37000 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 6e  * if SQLite is n
37010 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ot compiled with
37020 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
37030 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
37040 54 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  T]..*/.SQLITE_AP
37050 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  I int sqlite3_re
37060 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74  lease_memory(int
37070 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37080 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d  EF: Impose A Lim
37090 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a  it On Heap Size.
370a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
370b0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
370c0 69 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  it64() interface
370d0 20 73 65 74 73 20 61 6e 64 2f 6f 72 20 71 75 65   sets and/or que
370e0 72 69 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66 74  ries the.** soft
370f0 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d   limit on the am
37100 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d  ount of heap mem
37110 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20  ory that may be 
37120 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
37130 69 74 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ite..** ^SQLite 
37140 73 74 72 69 76 65 73 20 74 6f 20 6b 65 65 70 20  strives to keep 
37150 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 74 69 6c  heap memory util
37160 69 7a 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74 68  ization below th
37170 65 20 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20 6c  e soft heap.** l
37180 69 6d 69 74 20 62 79 20 72 65 64 75 63 69 6e 67  imit by reducing
37190 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
371a0 61 67 65 73 20 68 65 6c 64 20 69 6e 20 74 68 65  ages held in the
371b0 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61   page cache.** a
371c0 73 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73  s heap memory us
371d0 61 67 65 73 20 61 70 70 72 6f 61 63 68 65 73 20  ages approaches 
371e0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  the limit..** ^T
371f0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
37200 69 74 20 69 73 20 22 73 6f 66 74 22 20 62 65 63  it is "soft" bec
37210 61 75 73 65 20 65 76 65 6e 20 74 68 6f 75 67 68  ause even though
37220 20 53 51 4c 69 74 65 20 73 74 72 69 76 65 73 20   SQLite strives 
37230 74 6f 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f 77  to stay.** below
37240 20 74 68 65 20 6c 69 6d 69 74 2c 20 69 74 20 77   the limit, it w
37250 69 6c 6c 20 65 78 63 65 65 64 20 74 68 65 20 6c  ill exceed the l
37260 69 6d 69 74 20 72 61 74 68 65 72 20 74 68 61 6e  imit rather than
37270 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e 20   generate.** an 
37280 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65  [SQLITE_NOMEM] e
37290 72 72 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72 20  rror.  In other 
372a0 77 6f 72 64 73 2c 20 74 68 65 20 73 6f 66 74 20  words, the soft 
372b0 68 65 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20 69  heap limit .** i
372c0 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e  s advisory only.
372d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
372e0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
372f0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
37300 6c 69 6d 69 74 36 34 28 29 20 69 73 20 74 68 65  limit64() is the
37310 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20   size of.** the 
37320 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
37330 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c  prior to the cal
37340 6c 2e 20 20 5e 49 66 20 74 68 65 20 61 72 67 75  l.  ^If the argu
37350 6d 65 6e 74 20 4e 20 69 73 20 6e 65 67 61 74 69  ment N is negati
37360 76 65 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63 68  ve.** then no ch
37370 61 6e 67 65 20 69 73 20 6d 61 64 65 20 74 6f 20  ange is made to 
37380 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
37390 6d 69 74 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  mit.  Hence, the
373a0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a 65   current.** size
373b0 20 6f 66 20 74 68 65 20 73 6f 66 74 20 68 65 61   of the soft hea
373c0 70 20 6c 69 6d 69 74 20 63 61 6e 20 62 65 20 64  p limit can be d
373d0 65 74 65 72 6d 69 6e 65 64 20 62 79 20 69 6e 76  etermined by inv
373e0 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
373f0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
37400 36 34 28 29 20 77 69 74 68 20 61 20 6e 65 67 61  64() with a nega
37410 74 69 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tive argument..*
37420 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67  *.** ^If the arg
37430 75 6d 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f 20  ument N is zero 
37440 74 68 65 6e 20 74 68 65 20 73 6f 66 74 20 68 65  then the soft he
37450 61 70 20 6c 69 6d 69 74 20 69 73 20 64 69 73 61  ap limit is disa
37460 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  bled..**.** ^(Th
37470 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
37480 74 20 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65  t is not enforce
37490 64 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  d in the current
374a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
374b0 2a 2a 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  ** if one or mor
374c0 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 63  e of following c
374d0 6f 6e 64 69 74 69 6f 6e 73 20 61 72 65 20 74 72  onditions are tr
374e0 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ue:.**.** <ul>.*
374f0 2a 20 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74 20  * <li> The soft 
37500 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 73 65  heap limit is se
37510 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c  t to zero..** <l
37520 69 3e 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75 6e  i> Memory accoun
37530 74 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64  ting is disabled
37540 20 75 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e 61   using a combina
37550 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20  tion of the.**  
37560 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e      [sqlite3_con
37570 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
37580 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 2e  FIG_MEMSTATUS],.
37590 2e 2e 29 20 73 74 61 72 74 2d 74 69 6d 65 20 6f  ..) start-time o
375a0 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20  ption and.**    
375b0 20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45    the [SQLITE_DE
375c0 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d  FAULT_MEMSTATUS]
375d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
375e0 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e  tion..** <li> An
375f0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67   alternative pag
37600 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
37610 74 61 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66  tation is specif
37620 69 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ied using.**    
37630 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69    [sqlite3_confi
37640 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
37650 47 5f 50 43 41 43 48 45 5d 2c 2e 2e 2e 29 2e 0a  G_PCACHE],...)..
37660 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61 67 65  ** <li> The page
37670 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 73   cache allocates
37680 20 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65   from its own me
37690 6d 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69  mory pool suppli
376a0 65 64 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b 73  ed.**      by [s
376b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
376c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
376d0 47 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61  GECACHE],...) ra
376e0 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
376f0 20 20 66 72 6f 6d 20 74 68 65 20 68 65 61 70 2e    from the heap.
37700 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
37710 2a 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68  * Beginning with
37720 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
37730 33 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66 74 20  3.7.3, the soft 
37740 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e  heap limit is en
37750 66 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61 72 64  forced.** regard
37760 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
37770 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
37780 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
37790 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20  _MANAGEMENT].** 
377a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
377b0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
377c0 20 57 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e   With [SQLITE_EN
377d0 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
377e0 47 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20  GEMENT],.** the 
377f0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
37800 69 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e 20 65  is enforced on e
37810 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
37820 63 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f 75 74  cation.  Without
37830 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
37840 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
37850 4d 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66 74 20  MENT], the soft 
37860 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6f 6e  heap limit is on
37870 6c 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 77  ly enforced.** w
37880 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c  hen memory is al
37890 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 70  located by the p
378a0 61 67 65 20 63 61 63 68 65 2e 20 20 54 65 73 74  age cache.  Test
378b0 69 6e 67 20 73 75 67 67 65 73 74 73 20 74 68 61  ing suggests tha
378c0 74 20 62 65 63 61 75 73 65 0a 2a 2a 20 74 68 65  t because.** the
378d0 20 70 61 67 65 20 63 61 63 68 65 20 69 73 20 74   page cache is t
378e0 68 65 20 70 72 65 64 6f 6d 69 6e 61 74 65 20 6d  he predominate m
378f0 65 6d 6f 72 79 20 75 73 65 72 20 69 6e 20 53 51  emory user in SQ
37900 4c 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70  Lite, most.** ap
37910 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  plications will 
37920 61 63 68 69 65 76 65 20 61 64 65 71 75 61 74 65  achieve adequate
37930 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
37940 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77 69 74   enforcement wit
37950 68 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73 65 20  hout.** the use 
37960 6f 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  of [SQLITE_ENABL
37970 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
37980 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ENT]..**.** The 
37990 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 75 6e  circumstances un
379a0 64 65 72 20 77 68 69 63 68 20 53 51 4c 69 74 65  der which SQLite
379b0 20 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20 74 68   will enforce th
379c0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
379d0 74 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67 65 73  t may.** changes
379e0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
379f0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
37a00 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
37a10 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
37a20 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
37a30 69 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74  it64(sqlite3_int
37a40 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  64 N);../*.** CA
37a50 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
37a60 65 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d  ed Soft Heap Lim
37a70 69 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20  it Interface.** 
37a80 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
37a90 20 54 68 69 73 20 69 73 20 61 20 64 65 70 72 65   This is a depre
37aa0 63 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  cated version of
37ab0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f   the [sqlite3_so
37ac0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
37ad0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
37ae0 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69    This routine i
37af0 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68  s provided for h
37b00 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
37b10 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e  ibility.** only.
37b20 20 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63    All new applic
37b30 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73  ations should us
37b40 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
37b50 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
37b60 74 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65  t64()] interface
37b70 20 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 69   rather than thi
37b80 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  s one..*/.SQLITE
37b90 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
37ba0 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
37bb0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
37bc0 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a  mit(int N);.../*
37bd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
37be0 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41  tract Metadata A
37bf0 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66  bout A Column Of
37c00 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e   A Table.**.** ^
37c10 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
37c20 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62  urns metadata ab
37c30 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63  out a specific c
37c40 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69  olumn of a speci
37c50 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  fic.** database 
37c60 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65  table accessible
37c70 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61   using the [data
37c80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37c90 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65   handle.** passe
37ca0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66  d as the first f
37cb0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
37cc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
37cd0 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65  umn is identifie
37ce0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c  d by the second,
37cf0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
37d00 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a  h parameters to.
37d10 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
37d20 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
37d30 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65  rameter is eithe
37d40 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  r the name of th
37d50 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69  e database.** (i
37d60 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d  .e. "main", "tem
37d70 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63 68  p", or an attach
37d80 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e  ed database) con
37d90 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63  taining the spec
37da0 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f  ified.** table o
37db0 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69  r NULL. ^If it i
37dc0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c  s NULL, then all
37dd0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
37de0 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64  ses are searched
37df0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c  .** for the tabl
37e00 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
37e10 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20   algorithm used 
37e20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
37e30 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73  engine to.** res
37e40 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64  olve unqualified
37e50 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65   table reference
37e60 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  s..**.** ^The th
37e70 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
37e80 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
37e90 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74  s function are t
37ea0 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  he table and col
37eb0 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  umn.** name of t
37ec0 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
37ed0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
37ee0 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
37ef0 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  e parameters.** 
37f00 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  may be NULL..**.
37f10 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73 20  ** ^Metadata is 
37f20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74  returned by writ
37f30 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ing to the memor
37f40 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73  y locations pass
37f50 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a  ed as the 5th.**
37f60 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
37f70 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
37f80 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e  is function. ^An
37f90 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d  y of these argum
37fa0 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e  ents may be.** N
37fb0 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ULL, in which ca
37fc0 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  se the correspon
37fd0 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20  ding element of 
37fe0 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74  metadata is omit
37ff0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c  ted..**.** ^(<bl
38000 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
38010 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
38020 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61  ** <tr><th> Para
38030 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75  meter <th> Outpu
38040 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  t<br>Type <th>  
38050 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a  Description.**.*
38060 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c  * <tr><td> 5th <
38070 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
38080 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a  <td> Data type.*
38090 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c  * <tr><td> 6th <
380a0 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
380b0 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66  <td> Name of def
380c0 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ault collation s
380d0 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c  equence.** <tr><
380e0 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74  td> 7th <td> int
380f0 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
38100 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73  ue if column has
38110 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73   a NOT NULL cons
38120 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74  traint.** <tr><t
38130 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 8th <td> int 
38140 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
38150 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70  e if column is p
38160 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41  art of the PRIMA
38170 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74  RY KEY.** <tr><t
38180 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 9th <td> int 
38190 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
381a0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b  e if column is [
381b0 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a  AUTOINCREMENT].*
381c0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
381d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
381e0 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
381f0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
38200 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e  e character poin
38210 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f  ters returned fo
38220 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61  r the.** declara
38230 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f  tion type and co
38240 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
38250 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75   is valid only u
38260 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a  ntil the next.**
38270 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c   call to any SQL
38280 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e  ite API function
38290 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
382a0 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20  specified table 
382b0 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69  is actually a vi
382c0 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ew, an [error co
382d0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
382e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  .**.** ^If the s
382f0 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20  pecified column 
38300 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64  is "rowid", "oid
38310 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61  " or "_rowid_" a
38320 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45  nd an.** [INTEGE
38330 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63  R PRIMARY KEY] c
38340 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65  olumn has been e
38350 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
38360 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  ed, then the out
38370 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
38380 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68  s are set for th
38390 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  e explicitly dec
383a0 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28  lared column. ^(
383b0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a  If there is no.*
383c0 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  * explicitly dec
383d0 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50  lared [INTEGER P
383e0 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75  RIMARY KEY] colu
383f0 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  mn, then the out
38400 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
38410 73 20 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c  s are set as fol
38420 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  lows:.**.** <pre
38430 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79  >.**     data ty
38440 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a  pe: "INTEGER".**
38450 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73       collation s
38460 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59  equence: "BINARY
38470 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c  ".**     not nul
38480 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d  l: 0.**     prim
38490 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20  ary key: 1.**   
384a0 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74    auto increment
384b0 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a  : 0.** </pre>)^.
384c0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e  **.** ^(This fun
384d0 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f  ction may load o
384e0 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d  ne or more schem
384f0 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  as from database
38500 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a   files. If an.**
38510 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
38520 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73  ring this proces
38530 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71  s, or if the req
38540 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20  uested table or 
38550 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74  column.** cannot
38560 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65   be found, an [e
38570 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
38580 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72  turned and an er
38590 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74  ror message left
385a0 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61  .** in the [data
385b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
385c0 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65   (to be retrieve
385d0 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
385e0 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a  errmsg()).)^.**.
385f0 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73 20  ** ^This API is 
38600 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
38610 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
38620 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
38630 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
38640 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
38650 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
38660 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
38670 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ined..*/.SQLITE_
38680 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
38690 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74  table_column_met
386a0 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33  adata(.  sqlite3
386b0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
386c0 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69       /* Connecti
386d0 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  on handle */.  c
386e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
386f0 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61  me,        /* Da
38700 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e  tabase name or N
38710 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ULL */.  const c
38720 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c  har *zTableName,
38730 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61       /* Table na
38740 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  me */.  const ch
38750 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c  ar *zColumnName,
38760 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61      /* Column na
38770 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  me */.  char con
38780 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c  st **pzDataType,
38790 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44      /* OUTPUT: D
387a0 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70  eclared data typ
387b0 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
387c0 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20  t **pzCollSeq,  
387d0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f     /* OUTPUT: Co
387e0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
387f0 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   name */.  int *
38800 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20  pNotNull,       
38810 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54