System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact d1778ff0923583b6e1522ede4d9fa703f63826f6:


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 31 2e 20  ersion 3.7.6.1. 
00b0: 20 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c   By combining al
00c0: 6c 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c  l the individual
00d0: 20 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e   C code files in
00e0: 74 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67  to this .** sing
00f0: 6c 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74  le large file, t
0100: 68 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63  he entire code c
0110: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61  an be compiled a
0120: 73 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73  s a single trans
0130: 6c 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20  lation.** unit. 
0140: 20 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e   This allows man
0150: 79 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64  y compilers to d
0160: 6f 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  o optimizations 
0170: 74 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62  that would not b
0180: 65 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66  e.** possible if
0190: 20 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20   the files were 
01a0: 63 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74  compiled separat
01b0: 65 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63  ely.  Performanc
01c0: 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a  e improvements.*
01d0: 2a 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20  * of 5% or more 
01e0: 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65  are commonly see
01f0: 6e 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  n when SQLite is
0200: 20 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73   compiled as a s
0210: 69 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61  ingle.** transla
0220: 74 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a  tion unit..**.**
0230: 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c   This file is al
0240: 6c 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f  l you need to co
0250: 6d 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54  mpile SQLite.  T
0260: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20  o use SQLite in 
0270: 6f 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d  other.** program
0280: 73 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73  s, you need this
0290: 20 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73   file and the "s
02a0: 71 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72  qlite3.h" header
02b0: 20 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e   file that defin
02c0: 65 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61  es.** the progra
02d0: 6d 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  mming interface 
02e0: 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  to the SQLite li
02f0: 62 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20  brary.  (If you 
0300: 64 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20  do not have .** 
0310: 74 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20  the "sqlite3.h" 
0320: 68 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68  header file at h
0330: 61 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69  and, you will fi
0340: 6e 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64  nd a copy embedd
0350: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
0360: 20 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69   text of this fi
0370: 6c 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20  le.  Search for 
0380: 22 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69  "Begin file sqli
0390: 74 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74  te3.h" to find t
03a0: 68 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74  he start.** of t
03b0: 68 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69  he embedded sqli
03c0: 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c  te3.h header fil
03d0: 65 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63  e.) Additional c
03e0: 6f 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65  ode files may be
03f0: 20 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f   needed.** if yo
0400: 75 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72  u want a wrapper
0410: 20 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51   to interface SQ
0420: 4c 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63  Lite with your c
0430: 68 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d  hoice of program
0440: 6d 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65  ming.** language
0450: 2e 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74  . The code for t
0460: 68 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d  he "sqlite3" com
0470: 6d 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20  mand-line shell 
0480: 69 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20  is also in a.** 
0490: 73 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54  separate file. T
04a0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e  his file contain
04b0: 73 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20  s only code for 
04c0: 74 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20  the core SQLite 
04d0: 6c 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66  library..*/.#def
04e0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20  ine SQLITE_CORE 
04f0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
0500: 5f 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a  _AMALGAMATION 1.
0510: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50  #ifndef SQLITE_P
0520: 52 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20  RIVATE.# define 
0530: 53 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73  SQLITE_PRIVATE s
0540: 74 61 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66  tatic.#endif.#if
0550: 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a  ndef SQLITE_API.
0560: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
0570: 41 50 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a  API.#endif./****
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e  ********** Begin
0590: 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e   file sqliteInt.
05a0: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  h **************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a  *********/./*.**
05d0: 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20   2001 September 
05e0: 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  15.**.** The aut
05f0: 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f  hor disclaims co
0600: 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20  pyright to this 
0610: 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e  source code.  In
0620: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c   place of.** a l
0630: 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72  egal notice, her
0640: 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a  e is a blessing:
0650: 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f  .**.**    May yo
0660: 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f  u do good and no
0670: 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61  t evil..**    Ma
0680: 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69  y you find forgi
0690: 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73  veness for yours
06a0: 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20  elf and forgive 
06b0: 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61  others..**    Ma
06c0: 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65  y you share free
06d0: 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67  ly, never taking
06e0: 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67   more than you g
06f0: 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a  ive..**.********
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0740: 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e  *.** Internal in
0750: 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69  terface definiti
0760: 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a  ons for SQLite..
0770: 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53  **.*/.#ifndef _S
0780: 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66  QLITEINT_H_.#def
0790: 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48  ine _SQLITEINT_H
07a0: 5f 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23  _../*.** These #
07b0: 64 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65  defines should e
07c0: 6e 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20  nable >2GB file 
07d0: 73 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58  support on POSIX
07e0: 20 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   if the.** under
07f0: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
0800: 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20  system supports 
0810: 69 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c  it.  If the OS l
0820: 61 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69  acks.** large fi
0830: 6c 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69  le support, or i
0840: 66 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64  f the OS is wind
0850: 6f 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c  ows, these shoul
0860: 64 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a  d be no-ops..**.
0870: 2a 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a  ** Ticket #2739:
0880: 20 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45    The _LARGEFILE
0890: 5f 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75  _SOURCE macro mu
08a0: 73 74 20 61 70 70 65 61 72 20 62 65 66 6f 72 65  st appear before
08b0: 20 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23   any.** system #
08c0: 69 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65  includes.  Hence
08d0: 2c 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20  , this block of 
08e0: 63 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68 65  code must be the
08f0: 20 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63   very first.** c
0900: 6f 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63  ode in all sourc
0910: 65 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c  e files..**.** L
0920: 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72  arge file suppor
0930: 74 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65  t can be disable
0940: 64 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51  d using the -DSQ
0950: 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53  LITE_DISABLE_LFS
0960: 20 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68   switch.** on th
0970: 65 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61  e compiler comma
0980: 6e 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69  nd line.  This i
0990: 73 20 6e 65 63 65 73 73 61 72 79 20 69 66 20 79  s necessary if y
09a0: 6f 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67  ou are compiling
09b0: 0a 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20  .** on a recent 
09c0: 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64  machine (ex: Red
09d0: 20 48 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f   Hat 7.2) but yo
09e0: 75 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65  u want your code
09f0: 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61   to work.** on a
0a00: 6e 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20  n older machine 
0a10: 28 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30  (ex: Red Hat 6.0
0a20: 29 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69  ).  If you compi
0a30: 6c 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e  le on Red Hat 7.
0a40: 32 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69  2.** without thi
0a50: 73 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73  s option, LFS is
0a60: 20 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46   enable.  But LF
0a70: 53 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74  S does not exist
0a80: 20 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a   in the kernel.*
0a90: 2a 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30  * in Red Hat 6.0
0aa0: 2c 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f  , so the code wo
0ab0: 6e 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65  n't work.  Hence
0ac0: 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69  , for maximum bi
0ad0: 6e 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c  nary.** portabil
0ae0: 69 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f  ity you should o
0af0: 6d 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 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 31 22 0a 23       "3.7.6.1".#
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 34 2d 32 37 20 31     "2011-04-27 1
5a20: 36 3a 30 35 3a 34 32 20 37 62 34 37 39 62 39 62  6:05:42 7b479b9b
5a30: 65 65 39 33 64 66 39 30 39 65 64 65 63 64 34 34  ee93df909edecd44
5a40: 63 37 64 36 35 38 34 64 39 34 33 62 33 39 63 39  c7d6584d943b39c9
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 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
9a40: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
9a50: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
9a60: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (21<<8)).#define
9a70: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45   SQLITE_IOERR_SE
9a80: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EK              
9a90: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
9aa0: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (22<<8)).#define
9ab0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
9ac0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
9ad0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
9ae0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
9af0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
9b00: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
9b10: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
9b20: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
9b30: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
9b40: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
9b50: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
9b60: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  EN | (1<<8))../*
9b70: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
9b80: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
9b90: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
9ba0: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
9bb0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
9bc0: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
9bd0: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
9be0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9bf0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
9c00: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
9c10: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
9c20: 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  r to the xOpen m
9c30: 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20  ethod of the.** 
9c40: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
9c50: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
9c60: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
9c70: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
9c80: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
9c90: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9ca0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9cb0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
9cc0: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
9cd0: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
9ce0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9cf0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9d00: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
9d10: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
9d20: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
9d30: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9d40: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9d50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
9d60: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
9d70: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* 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 45 58 43   SQLITE_OPEN_EXC
9da0: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
9db0: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* 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 41 55 54   SQLITE_OPEN_AUT
9de0: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
9df0: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* 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 4d 41 49   SQLITE_OPEN_MAI
9e20: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
9e30: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* 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 54 45 4d   SQLITE_OPEN_TEM
9e60: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
9e70: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* 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 52 41   SQLITE_OPEN_TRA
9ea0: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
9eb0: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* 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 4d 41 49   SQLITE_OPEN_MAI
9ee0: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
9ef0: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* 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 54 45 4d   SQLITE_OPEN_TEM
9f20: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
9f30: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* 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 53 55 42   SQLITE_OPEN_SUB
9f60: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
9f70: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
9f80: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9f90: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
9fa0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
9fb0: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
9fc0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9fd0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
9fe0: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
9ff0: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
a000: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a010: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a020: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
a030: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
a040: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
a050: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a060: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a070: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
a080: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
a090: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
a0a0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a0b0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a0c0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
a0d0: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
a0e0: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
a0f0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a100: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a110: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
a120: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
a130: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
a140: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
a150: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
a160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
a170: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
a180: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
a190: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
a1a0: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
a1b0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
a1c0: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
a1d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
a1e0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
a1f0: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
a200: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
a210: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74   vector of the t
a220: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
a230: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
a240: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
a250: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
a260: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
a270: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
a280: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
a290: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
a2a0: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
a2b0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
a2c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
a2d0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
a2e0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
a2f0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
a300: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
a310: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a320: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
a330: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
a340: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
a350: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
a360: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
a370: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
a380: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
a390: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
a3a0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
a3b0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
a3c0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
a3d0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
a3e0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
a3f0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
a400: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
a410: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
a420: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
a430: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
a440: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
a450: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
a460: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
a470: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
a480: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
a490: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
a4a0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
a4b0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
a4c0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
a4d0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
a4e0: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
a4f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
a500: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
a510: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
a520: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
a530: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
a540: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
a550: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
a560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
a570: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
a580: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
a590: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
a5a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a5b0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
a5c0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
a5d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
a5e0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
a5f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a600: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
a610: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
a620: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
a630: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
a640: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
a650: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
a660: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
a670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a680: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
a690: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
a6a0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
a6b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a6c0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
a6d0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
a6e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
a6f0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
a700: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
a710: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
a720: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
a730: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
a740: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
a750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
a760: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
a770: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
a780: 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  800../*.** CAPI3
a790: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
a7a0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
a7b0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
a7c0: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
a7d0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
a7e0: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
a7f0: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
a800: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
a810: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
a820: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
a830: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
a840: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
a850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a860: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
a870: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
a880: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
a890: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
a8a0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
a8b0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
a8c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
a8d0: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
a8e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a8f0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
a900: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
a910: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
a920: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
a930: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
a940: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
a950: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
a960: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
a970: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
a980: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
a990: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
a9a0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
a9b0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
a9c0: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
a9d0: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
a9e0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
a9f0: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
aa00: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
aa10: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
aa20: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
aa30: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
aa40: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
aa50: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
aa60: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
aa70: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
aa80: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
aa90: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
aaa0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
aab0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
aac0: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
aad0: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
aae0: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
aaf0: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
ab00: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
ab10: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
ab20: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
ab30: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
ab40: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
ab50: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
ab60: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
ab70: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
ab80: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
ab90: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
aba0: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
abb0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
abc0: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
abd0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
abe0: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
abf0: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
ac00: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
ac10: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
ac20: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
ac30: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
ac40: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
ac50: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
ac60: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
ac70: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
ac80: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
ac90: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
aca0: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
acb0: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
acc0: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
acd0: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
ace0: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
acf0: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
ad00: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
ad10: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
ad20: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
ad30: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
ad40: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
ad50: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
ad60: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
ad70: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
ad80: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
ad90: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
ada0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
adb0: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
adc0: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
add0: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
ade0: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
adf0: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
ae00: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
ae10: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
ae20: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
ae30: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
ae40: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
ae50: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
ae60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
ae70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
ae80: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
ae90: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
aea0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
aeb0: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
aec0: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
aed0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
aee0: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
aef0: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
af00: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
af10: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
af20: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
af30: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
af40: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
af50: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
af60: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
af70: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
af80: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
af90: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
afa0: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
afb0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
afc0: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
afd0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
afe0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
aff0: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
b000: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
b010: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
b020: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
b030: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
b040: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
b050: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
b060: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
b070: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
b080: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
b090: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
b0a0: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
b0b0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
b0c0: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
b0d0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
b0e0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
b0f0: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
b100: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
b110: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
b120: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
b130: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70  sqlite3_vfs] xOp
b140: 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  en method popula
b150: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
b160: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
b170: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
b180: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
b190: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
b1a0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
b1b0: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
b1c0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
b1d0: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
b1e0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
b1f0: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
b200: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
b210: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
b220: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
b230: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
b240: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
b250: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
b260: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
b270: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
b280: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
b290: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
b2a0: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
b2b0: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
b2c0: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
b2d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
b2e0: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
b2f0: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
b300: 76 65 6e 20 69 66 20 74 68 65 20 78 4f 70 65 6e  ven if the xOpen
b310: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
b320: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
b330: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
b340: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
b350: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
b360: 20 61 20 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a   a failed xOpen.
b370: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 78 4f  ** is for the xO
b380: 70 65 6e 20 74 6f 20 73 65 74 20 74 68 65 20 73  pen to set the s
b390: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
b3a0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20  hods element to 
b3b0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
b3c0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
b3d0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
b3e0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
b3f0: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
b400: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
b410: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
b420: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
b430: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
b440: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
b450: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
b460: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
b470: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
b480: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
b490: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
b4a0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
b4b0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
b4c0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
b4d0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
b4e0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
b4f0: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
b500: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
b510: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
b520: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
b530: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
b540: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
b550: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
b560: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
b570: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
b580: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
b590: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
b5a0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
b5b0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
b5c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
b5d0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
b5e0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
b5f0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
b600: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
b610: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
b620: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
b630: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
b640: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
b650: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
b660: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
b670: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
b680: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
b690: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
b6a0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
b6b0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
b6c0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
b6d0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
b6e0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
b6f0: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
b700: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
b710: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
b720: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
b730: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
b740: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
b750: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
b760: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
b770: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
b780: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
b790: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
b7a0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
b7b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
b7c0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
b7d0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
b7e0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
b7f0: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
b800: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
b810: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
b820: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
b830: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
b840: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
b850: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
b860: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
b870: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
b880: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
b890: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
b8a0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
b8b0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
b8c0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
b8d0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
b8e0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
b8f0: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
b900: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
b910: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
b920: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
b930: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
b940: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
b950: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
b960: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
b970: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
b980: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
b990: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
b9a0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
b9b0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
b9c0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
b9d0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
b9e0: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
b9f0: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
ba00: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
ba10: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
ba20: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
ba30: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
ba40: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
ba50: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
ba60: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
ba70: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
ba80: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
ba90: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
baa0: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
bab0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
bac0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
bad0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
bae0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
baf0: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
bb00: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
bb10: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
bb20: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
bb30: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
bb40: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
bb50: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
bb60: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
bb70: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
bb80: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
bb90: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
bba0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
bbb0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
bbc0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
bbd0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
bbe0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
bbf0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
bc00: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
bc10: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
bc20: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
bc30: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
bc40: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
bc50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
bc60: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
bc70: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
bc80: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <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 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
bcb0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
bcc0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
bcd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
bce0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
bcf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
bd00: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
bd10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
bd20: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
bd30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
bd40: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
bd50: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
bd60: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
bd70: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
bd80: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
bd90: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
bda0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
bdb0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
bdc0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
bdd0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
bde0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
bdf0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
be00: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
be10: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
be20: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
be30: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
be40: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
be50: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
be60: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
be70: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
be80: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
be90: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
bea0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
beb0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
bec0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
bed0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
bee0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
bef0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
bf00: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
bf10: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
bf20: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
bf30: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
bf40: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
bf50: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
bf60: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
bf70: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
bf80: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
bf90: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
bfa0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
bfb0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
bfc0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
bfd0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
bfe0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
bff0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
c000: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
c010: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
c020: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
c030: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
c040: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
c050: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
c060: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
c070: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
c080: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
c090: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
c0a0: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
c0b0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
c0c0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
c0d0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
c0e0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
c0f0: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
c100: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
c110: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
c120: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
c130: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
c140: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
c150: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
c160: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
c170: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
c180: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
c190: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
c1a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
c1b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
c1c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
c1d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
c1e0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
c1f0: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
c200: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
c210: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
c220: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
c230: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
c240: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
c250: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
c260: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
c270: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
c280: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
c290: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
c2a0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
c2b0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
c2c0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
c2d0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
c2e0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
c2f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
c300: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
c310: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
c320: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
c330: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
c340: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
c350: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
c360: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
c370: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
c380: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
c390: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
c3a0: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
c3b0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
c3c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
c3d0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
c3e0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
c3f0: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
c400: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
c410: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
c420: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
c430: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
c440: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
c450: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
c460: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
c470: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
c480: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
c490: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
c4a0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
c4b0: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
c4c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
c4d0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
c4e0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
c4f0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
c500: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f  version 2 */.  /
c510: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
c520: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
c530: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
c540: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
c550: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
c560: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
c570: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
c580: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
c590: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
c5a0: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
c5b0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
c5c0: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
c5d0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
c5e0: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
c5f0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
c600: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
c610: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
c620: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c630: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
c640: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
c650: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
c660: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
c670: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
c680: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
c690: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
c6a0: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
c6b0: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
c6c0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
c6d0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
c6e0: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
c6f0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
c700: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
c710: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
c720: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
c730: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
c740: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
c750: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
c760: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
c770: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
c780: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
c790: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
c7a0: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
c7b0: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
c7c0: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
c7d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
c7e0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
c7f0: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
c800: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
c810: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
c820: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
c830: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
c840: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
c850: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
c860: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
c870: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
c880: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
c890: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
c8a0: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
c8b0: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
c8c0: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
c8d0: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
c8e0: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
c8f0: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
c900: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
c910: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
c920: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
c930: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
c940: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
c950: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
c960: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
c970: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
c980: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
c990: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
c9a0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
c9b0: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
c9c0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
c9d0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
c9e0: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
c9f0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
ca00: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
ca10: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
ca20: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
ca30: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
ca40: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
ca50: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
ca60: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
ca70: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
ca80: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
ca90: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
caa0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
cab0: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
cac0: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
cad0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
cae0: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
caf0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
cb00: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
cb10: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
cb20: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
cb30: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ems..**.** The [
cb40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
cb50: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
cb60: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
cb70: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
cb80: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
cb90: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
cba0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
cbb0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
cbc0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
cbd0: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
cbe0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
cbf0: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
cc00: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
cc10: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
cc20: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ..**.** ^(The [S
cc30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
cc40: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
cc50: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
cc60: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
cc70: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
cc80: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
cc90: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
cca0: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
ccb0: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
ccc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ccd0: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
cce0: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
ccf0: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
cd00: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
cd10: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
cd20: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
cd30: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
cd40: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
cd50: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
cd60: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
cd70: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
cd80: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
cd90: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
cda0: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
cdb0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
cdc0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
cdd0: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
cde0: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
cdf0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
ce00: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
ce10: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
ce20: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
ce30: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
ce40: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
ce50: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a  ecialized VFSes.
ce60: 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  ** that do requi
ce70: 72 65 20 69 74 2e 20 20 0a 2a 2f 0a 23 64 65 66  re it.  .*/.#def
ce80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ce90: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
cea0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
ceb0: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
cec0: 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66  FILE      2.#def
ced0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
cee0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
cef0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
cf00: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
cf10: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
cf20: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cf30: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
cf40: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
cf50: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
cf60: 49 5a 45 20 20 20 20 20 20 20 36 0a 23 64 65 66  IZE       6.#def
cf70: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cf80: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
cf90: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
cfa0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
cfb0: 49 54 54 45 44 20 20 20 20 20 38 0a 0a 0a 2f 2a  ITTED     8.../*
cfc0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
cfd0: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
cfe0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
cff0: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
d000: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
d010: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
d020: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
d030: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
d040: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
d050: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
d060: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
d070: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
d080: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
d090: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
d0a0: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
d0b0: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
d0c0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
d0d0: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
d0e0: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
d0f0: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
d100: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
d110: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
d120: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
d130: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
d140: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
d150: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
d160: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e   Object.**.** An
d170: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
d180: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
d190: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
d1a0: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
d1b0: 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20  n.** the SQLite 
d1c0: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64  core and the und
d1d0: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
d1e0: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22  g system.  The "
d1f0: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  vfs".** in the n
d200: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63  ame of the objec
d210: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69  t stands for "vi
d220: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
d230: 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  m"..**.** The va
d240: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
d250: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
d260: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
d270: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
d280: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
d290: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
d2a0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
d2b0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
d2c0: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
d2d0: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
d2e0: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
d2f0: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
d300: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
d310: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
d320: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
d330: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
d340: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
d350: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
d360: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
d370: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
d380: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
d390: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
d3a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
d3b0: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
d3c0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
d3d0: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
d3e0: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
d3f0: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
d400: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
d410: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
d420: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
d430: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
d440: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
d450: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
d460: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
d470: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
d480: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
d490: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
d4a0: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
d4b0: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
d4c0: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
d4d0: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
d4e0: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
d4f0: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
d500: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
d510: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
d520: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
d530: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
d540: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
d550: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
d560: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
d570: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
d580: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
d590: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
d5a0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
d5b0: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
d5c0: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
d5d0: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
d5e0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
d5f0: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
d600: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
d610: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
d620: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
d630: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
d640: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
d650: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
d660: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
d670: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
d680: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
d690: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
d6a0: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
d6b0: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
d6c0: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
d6d0: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
d6e0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
d6f0: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
d700: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
d710: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
d720: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
d730: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
d740: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
d750: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  .**.** ^SQLite g
d760: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
d770: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
d780: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a  ameter to xOpen.
d790: 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ** is either a N
d7a0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73  ULL pointer or s
d7b0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a  tring obtained.*
d7c0: 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68  * from xFullPath
d7d0: 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f  name() with an o
d7e0: 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61  ptional suffix a
d7f0: 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73  dded..** ^If a s
d800: 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74  uffix is added t
d810: 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  o the zFilename 
d820: 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69  parameter, it wi
d830: 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66  ll.** consist of
d840: 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68   a single "-" ch
d850: 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64  aracter followed
d860: 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e   by no more than
d870: 0a 2a 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d 65  .** 10 alphanume
d880: 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63  ric and/or "-" c
d890: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53  haracters..** ^S
d8a0: 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75  QLite further gu
d8b0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a  arantees that.**
d8c0: 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
d8d0: 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e   be valid and un
d8e0: 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43  changed until xC
d8f0: 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c  lose() is.** cal
d900: 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20  led. Because of 
d910: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
d920: 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tence,.** the [s
d930: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
d940: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
d950: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
d960: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
d970: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
d980: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
d990: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
d9a0: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
d9b0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
d9c0: 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  o xOpen is a NUL
d9d0: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
d9e0: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
d9f0: 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ent its own temp
da00: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
da10: 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65  he file.  ^Whene
da20: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
da30: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
da40: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
da50: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
da60: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
da70: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
da80: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
da90: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
daa0: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  LOSE]..**.** The
dab0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
dac0: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
dad0: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
dae0: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
daf0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
db00: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
db10: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
db20: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
db30: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
db40: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
db50: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
db60: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
db70: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
db80: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
db90: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20  EN_CREATE]. .** 
dba0: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
dbb0: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
dbc0: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
dbd0: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
dbe0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
dbf0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20  OPEN_READONLY]. 
dc00: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
dc10: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
dc20: 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51   set..**.** ^(SQ
dc30: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
dc40: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
dc50: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
dc60: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
dc70: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
dc80: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
dc90: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
dca0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
dcb0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
dcc0: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
dcd0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
dce0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
dcf0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
dd00: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
dd10: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
dd20: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
dd30: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
dd40: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
dd50: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
dd60: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
dd70: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
dd80: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
dd90: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
dda0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57    [SQLITE_OPEN_W
ddb0: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  AL].** </ul>)^.*
ddc0: 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f  *.** The file I/
ddd0: 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  O implementation
dde0: 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a   can use the obj
ddf0: 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74  ect type flags t
de00: 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  o.** change the 
de10: 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74  way it deals wit
de20: 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78  h files.  For ex
de30: 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
de40: 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f  ation.** that do
de50: 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75  es not care abou
de60: 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79  t crash recovery
de70: 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67   or rollback mig
de80: 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f  ht make.** the o
de90: 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c  pen of a journal
dea0: 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20   file a no-op.  
deb0: 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a  Writes to this j
dec0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20  ournal would.** 
ded0: 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20  also be no-ops, 
dee0: 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20  and any attempt 
def0: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
df00: 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  nal would return
df10: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  .** SQLITE_IOERR
df20: 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d  .  Or the implem
df30: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72  entation might r
df40: 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20  ecognize that a 
df50: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
df60: 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70   will be doing p
df70: 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74  age-aligned sect
df80: 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69  or reads and wri
df90: 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a  tes in a random.
dfa0: 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74  ** order and set
dfb0: 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73   up its I/O subs
dfc0: 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c  ystem accordingl
dfd0: 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  y..**.** SQLite 
dfe0: 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
dff0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
e000: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
e010: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a   xOpen method:.*
e020: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
e030: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  > [SQLITE_OPEN_D
e040: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
e050: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
e060: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a  EN_EXCLUSIVE].**
e070: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
e080: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
e090: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
e0a0: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
e0b0: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
e0c0: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
e0d0: 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b   closed.  ^The [
e0e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
e0f0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
e100: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
e110: 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64  MP databases and
e120: 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c   their journals,
e130: 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61   transient.** da
e140: 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62  tabases, and sub
e150: 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20  journals..**.** 
e160: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
e170: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
e180: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
e190: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
e1a0: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
e1b0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
e1c0: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
e1d0: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
e1e0: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
e1f0: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
e200: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
e210: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
e220: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
e230: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
e240: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
e250: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
e260: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
e270: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
e280: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
e290: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
e2a0: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
e2b0: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
e2c0: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
e2d0: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
e2e0: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
e2f0: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
e300: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
e310: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
e320: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
e330: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  access..**.** ^A
e340: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
e350: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
e360: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
e370: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
e380: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
e390: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
e3a0: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
e3b0: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
e3c0: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65  t to xOpen.  The
e3d0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
e3e0: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
e3f0: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
e400: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
e410: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
e420: 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a   in.  Note that.
e430: 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  ** the xOpen met
e440: 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65  hod must set the
e450: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
e460: 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72  ethods to either
e470: 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c  .** a valid [sql
e480: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
e490: 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55   object or to NU
e4a0: 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20  LL.  xOpen must 
e4b0: 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20  do.** this even 
e4c0: 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c  if the open fail
e4d0: 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63  s.  SQLite expec
e4e0: 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69  ts that the sqli
e4f0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
e500: 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c  s.** element wil
e510: 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72  l be valid after
e520: 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72   xOpen returns r
e530: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
e540: 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66   success.** or f
e550: 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f  ailure of the xO
e560: 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  pen call..**.** 
e570: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
e580: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
e590: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
e5a0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
e5b0: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
e5c0: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
e5d0: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
e5e0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
e5f0: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
e600: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
e610: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
e620: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
e630: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
e640: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
e650: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
e660: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
e670: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
e680: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
e690: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
e6a0: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
e6b0: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
e6c0: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
e6d0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
e6e0: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
e6f0: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
e700: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
e710: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
e720: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
e730: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
e740: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
e750: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
e760: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
e770: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
e780: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
e790: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
e7a0: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
e7b0: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
e7c0: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
e7d0: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
e7e0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
e7f0: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
e800: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
e810: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
e820: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
e830: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
e840: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
e850: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
e860: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
e870: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
e880: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
e890: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
e8a0: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
e8b0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
e8c0: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
e8d0: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
e8e0: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
e8f0: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
e900: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
e910: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
e920: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
e930: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
e940: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
e950: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
e960: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
e970: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
e980: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
e990: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
e9a0: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
e9b0: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
e9c0: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
e9d0: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
e9e0: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
e9f0: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
ea00: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
ea10: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
ea20: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
ea30: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
ea40: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
ea50: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
ea60: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
ea70: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
ea80: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
ea90: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
eaa0: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
eab0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
eac0: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
ead0: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
eae0: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
eaf0: 72 20 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38  r multipled by 8
eb00: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
eb10: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
eb20: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
eb30: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
eb40: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
eb50: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
eb60: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
eb70: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
eb80: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
eb90: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
eba0: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
ebb0: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
ebc0: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
ebd0: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
ebe0: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
ebf0: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
ec00: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
ec10: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
ec20: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
ec30: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
ec40: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
ec50: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
ec60: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
ec70: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
ec80: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
ec90: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
eca0: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
ecb0: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
ecc0: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
ecd0: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
ece0: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
ecf0: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
ed00: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
ed10: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
ed20: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
ed30: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
ed40: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
ed50: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
ed60: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
ed70: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
ed80: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
ed90: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
eda0: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
edb0: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
edc0: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
edd0: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
ede0: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
edf0: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
ee00: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
ee10: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
ee20: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
ee30: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
ee40: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
ee50: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
ee60: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
ee70: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
ee80: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
ee90: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
eea0: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
eeb0: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
eec0: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
eed0: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
eee0: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
eef0: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
ef00: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
ef10: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
ef20: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
ef30: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
ef40: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
ef50: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
ef60: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
ef70: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
ef80: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
ef90: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
efa0: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
efb0: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
efc0: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
efd0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
efe0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
eff0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
f000: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
f010: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
f020: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
f030: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
f040: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
f050: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
f060: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
f070: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
f080: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
f090: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
f0a0: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
f0b0: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
f0c0: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
f0d0: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
f0e0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
f0f0: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
f100: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
f110: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
f120: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
f130: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
f140: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
f150: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
f160: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
f170: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
f180: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
f190: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
f1a0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
f1b0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
f1c0: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
f1d0: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
f1e0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
f1f0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
f200: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
f210: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
f220: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
f230: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
f240: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
f250: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
f260: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
f270: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
f280: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
f290: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
f2a0: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
f2b0: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
f2c0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
f2d0: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
f2e0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
f2f0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
f300: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
f310: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
f320: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
f330: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
f340: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
f350: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
f360: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
f370: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
f380: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
f390: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
f3a0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
f3b0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
f3c0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
f3d0: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
f3e0: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
f3f0: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
f400: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
f410: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
f420: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
f430: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
f440: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
f450: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
f460: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
f470: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
f480: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
f490: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
f4a0: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
f4b0: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
f4c0: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
f4d0: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
f4e0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
f4f0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
f500: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
f510: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
f520: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
f530: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
f540: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
f550: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
f560: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
f570: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
f580: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
f590: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
f5a0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
f5b0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
f5c0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
f5d0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
f5e0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
f5f0: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
f600: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
f610: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
f620: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
f630: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
f640: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
f650: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
f660: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f670: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
f680: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
f690: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
f6a0: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
f6b0: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
f6c0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
f6d0: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
f6e0: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
f6f0: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
f700: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
f710: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
f720: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
f730: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
f740: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
f750: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
f760: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
f770: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
f780: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
f790: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
f7a0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
f7b0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
f7c0: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
f7d0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
f7e0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
f7f0: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
f800: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
f810: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
f820: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
f830: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
f840: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
f850: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
f860: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
f870: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
f880: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
f890: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
f8a0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
f8b0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
f8c0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f8d0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
f8e0: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
f8f0: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
f900: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
f910: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
f920: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
f930: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
f940: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
f950: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
f960: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
f970: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
f980: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
f990: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
f9a0: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
f9b0: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
f9c0: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
f9d0: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
f9e0: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
f9f0: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
fa00: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
fa10: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
fa20: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
fa30: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
fa40: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
fa50: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
fa60: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
fa70: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
fa80: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
fa90: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
faa0: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
fab0: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
fac0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
fad0: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
fae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
faf0: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
fb00: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
fb10: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
fb20: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
fb30: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
fb40: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
fb50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
fb60: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
fb70: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
fb80: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
fb90: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
fba0: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
fbb0: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
fbc0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
fbd0: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
fbe0: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
fbf0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
fc00: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
fc10: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
fc20: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
fc30: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
fc40: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
fc50: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
fc60: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
fc70: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
fc80: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
fc90: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
fca0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
fcb0: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
fcc0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
fcd0: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
fce0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
fcf0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
fd00: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
fd10: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
fd20: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
fd30: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
fd40: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
fd50: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
fd60: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
fd70: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
fd80: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
fd90: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
fda0: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
fdb0: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
fdc0: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
fdd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
fde0: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
fdf0: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
fe00: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
fe10: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
fe20: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
fe30: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
fe40: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
fe50: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
fe60: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
fe70: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
fe80: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
fe90: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
fea0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
feb0: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
fec0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
fed0: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
fee0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
fef0: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
ff00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
ff10: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
ff20: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
ff30: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
ff40: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
ff50: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
ff60: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
ff70: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
ff80: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
ff90: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
ffa0: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
ffb0: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
ffc0: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
ffd0: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
ffe0: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
fff0: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
10000 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10010 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
10020 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
10030 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
10040 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
10050 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
10060 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10070 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
10080 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
10090 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
100a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
100b0 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
100c0 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
100d0 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
100e0 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
100f0 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
10100 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
10110 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
10120 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
10130 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
10140 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
10150 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
10160 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
10170 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
10180 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
10190 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
101a0 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
101b0 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
101c0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
101d0 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
101e0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
101f0 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
10200 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
10210 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
10220 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
10230 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
10240 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
10250 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
10260 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
10270 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
10280 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
10290 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
102a0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
102b0 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
102c0 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
102d0 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
102e0 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
102f0 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
10300 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
10310 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
10320 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
10330 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
10340 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
10350 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
10360 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10370 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
10380 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
10390 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
103a0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
103b0 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
103c0 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
103d0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
103e0 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
103f0 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
10400 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10410 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
10420 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
10430 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
10440 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
10450 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
10460 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
10470 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
10480 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10490 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
104a0 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
104b0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
104c0 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
104d0 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
104e0 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
104f0 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
10500 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
10510 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
10520 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
10530 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
10540 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
10550 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
10560 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
10570 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
10580 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
10590 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
105a0 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
105b0 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
105c0 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
105d0 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
105e0 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
105f0 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
10600 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
10610 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
10620 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
10630 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
10640 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
10650 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
10660 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
10670 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
10680 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
10690 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
106a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
106b0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
106c0 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
106d0 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
106e0 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
106f0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
10700 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
10710 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
10720 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
10730 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
10740 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
10750 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
10760 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10770 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
10780 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
10790 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
107a0 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
107b0 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
107c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
107d0 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
107e0 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
107f0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10800 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
10810 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
10820 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
10830 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
10840 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
10850 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
10860 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
10870 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
10880 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
10890 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
108a0 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
108b0 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
108c0 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
108d0 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
108e0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
108f0 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
10900 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
10910 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
10920 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
10930 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
10940 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
10950 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
10960 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
10970 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
10980 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
10990 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
109a0 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
109b0 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
109c0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
109d0 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
109e0 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
109f0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
10a00 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
10a10 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
10a20 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10a30 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
10a40 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
10a50 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
10a60 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
10a70 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
10a80 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
10a90 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
10aa0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
10ab0 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
10ac0 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
10ad0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10ae0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
10af0 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
10b00 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
10b10 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
10b20 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
10b30 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
10b40 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
10b50 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
10b60 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
10b70 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
10b80 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
10b90 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
10ba0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
10bb0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
10bc0 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
10bd0 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
10be0 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
10bf0 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
10c00 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
10c10 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
10c20 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
10c30 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
10c40 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
10c50 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
10c60 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
10c70 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
10c80 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
10c90 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
10ca0 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
10cb0 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
10cc0 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
10cd0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
10ce0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
10cf0 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
10d00 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
10d10 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
10d20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
10d30 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
10d40 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
10d50 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
10d60 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
10d70 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
10d80 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10d90 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
10da0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
10db0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
10dc0 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
10dd0 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
10de0 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
10df0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10e00 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
10e10 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
10e20 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
10e30 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
10e40 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
10e50 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
10e60 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10e70 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
10e80 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
10e90 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
10ea0 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
10eb0 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
10ec0 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
10ed0 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
10ee0 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
10ef0 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
10f00 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
10f10 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
10f20 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
10f30 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
10f40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
10f50 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
10f60 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
10f70 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
10f80 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
10f90 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
10fa0 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
10fb0 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
10fc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
10fd0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10fe0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
10ff0 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
11000 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
11010 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
11020 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
11030 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
11040 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49  failure..*/.SQLI
11050 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
11060 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
11070 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
11080 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
11090 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  down(void);.SQLI
110a0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
110b0 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
110c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
110d0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
110e0 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
110f0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
11100 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
11110 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65  ibrary.**.** The
11120 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
11130 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
11140 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
11150 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
11160 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
11170 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
11180 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
11190 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
111a0 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
111b0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
111c0 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
111d0 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
111e0 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
111f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
11200 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
11210 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
11220 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
11230 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
11240 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
11250 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
11260 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
11270 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
11280 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
11290 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
112a0 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
112b0 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
112c0 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
112d0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
112e0 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
112f0 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
11300 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
11310 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
11320 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
11330 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
11340 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
11350 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
11360 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
11370 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
11380 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
11390 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
113a0 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
113b0 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
113c0 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
113d0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
113e0 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
113f0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
11400 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
11410 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
11420 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
11430 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
11440 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
11450 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
11460 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
11470 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
11480 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
11490 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
114a0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
114b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
114c0 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
114d0 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
114e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
114f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
11500 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
11510 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  er.** [SQLITE_CO
11520 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11530 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  D | configuratio
11540 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
11550 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
11560 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
11570 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
11580 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
11590 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
115a0 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
115b0 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45  g on the [SQLITE
115c0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
115d0 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61  READ | configura
115e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20  tion option].** 
115f0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
11600 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  ument..**.** ^Wh
11610 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69  en a configurati
11620 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  on option is set
11630 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
11640 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  () returns [SQLI
11650 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74  TE_OK]..** ^If t
11660 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b  he option is unk
11670 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69  nown or SQLite i
11680 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20  s unable to set 
11690 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68  the option.** th
116a0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
116b0 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
116c0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ro [error code].
116d0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
116e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
116f0 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
11700 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
11710 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
11720 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a   connections.**.
11730 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
11740 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
11750 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
11760 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
11770 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
11780 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
11790 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
117a0 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
117b0 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
117c0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
117d0 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
117e0 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
117f0 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
11800 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11810 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
11820 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11830 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
11840 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
11850 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
11860 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
11870 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
11880 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
11890 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
118a0 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
118b0 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
118c0 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
118d0 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
118e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
118f0 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
11900 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
11910 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
11920 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
11930 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
11940 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
11950 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
11960 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
11970 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
11980 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
11990 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
119a0 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
119b0 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  sful..*/.SQLITE_
119c0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
119d0 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
119e0 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
119f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11a00 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
11a10 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
11a20 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
11a30 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
11a40 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
11a50 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
11a60 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
11a70 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
11a80 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
11a90 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
11aa0 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
11ab0 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
11ac0 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
11ad0 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
11ae0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
11af0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
11b00 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
11b10 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
11b20 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
11b30 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
11b40 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
11b50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
11b60 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
11b70 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
11b80 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
11b90 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
11ba0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
11bb0 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
11bc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
11bd0 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
11be0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
11bf0 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
11c00 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
11c10 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
11c20 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
11c30 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
11c40 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
11c50 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
11c60 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
11c70 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
11c80 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
11c90 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
11ca0 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
11cb0 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
11cc0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
11cd0 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
11ce0 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
11cf0 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
11d00 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
11d10 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
11d20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
11d30 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
11d40 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
11d50 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
11d60 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
11d70 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
11d80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
11d90 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
11da0 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
11db0 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
11dc0 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
11dd0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
11de0 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
11df0 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
11e00 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
11e10 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
11e20 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
11e30 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
11e40 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
11e50 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
11e60 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
11e70 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
11e80 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
11e90 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78 46 72 65  xMalloc and xFre
11ea0 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
11eb0 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
11ec0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
11ed0 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  e() functions fr
11ee0 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
11ef0 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68  C library..** Th
11f00 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f  e xRealloc metho
11f10 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  d must work like
11f20 20 72 65 61 6c 6c 6f 63 28 29 20 66 72 6f 6d 20   realloc() from 
11f30 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
11f40 69 62 72 61 72 79 0a 2a 2a 20 77 69 74 68 20 74  ibrary.** with t
11f50 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74 68 61  he exception tha
11f60 74 20 69 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t if the second 
11f70 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 52 65 61  argument to xRea
11f80 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  lloc is zero,.**
11f90 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73 74 20 62   xRealloc must b
11fa0 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d  e a no-op - it m
11fb0 75 73 74 20 6e 6f 74 20 70 65 72 66 6f 72 6d 20  ust not perform 
11fc0 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  any allocation o
11fd0 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 69 6f  r.** deallocatio
11fe0 6e 2e 20 20 5e 53 51 4c 69 74 65 20 67 75 61 72  n.  ^SQLite guar
11ff0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
12000 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
12010 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
12020 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
12030 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
12040 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
12050 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f  undup..** And so
12060 20 69 6e 20 63 61 73 65 73 20 77 68 65 72 65 20   in cases where 
12070 78 52 6f 75 6e 64 75 70 20 61 6c 77 61 79 73 20  xRoundup always 
12080 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69  returns a positi
12090 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78 52  ve number,.** xR
120a0 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65 72 66 6f  ealloc can perfo
120b0 72 6d 20 65 78 61 63 74 6c 79 20 61 73 20 74 68  rm exactly as th
120c0 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61  e standard libra
120d0 72 79 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ry realloc() and
120e0 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20 69 6e 20  .** still be in 
120f0 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69 74 68 20  compliance with 
12100 74 68 69 73 20 73 70 65 63 69 66 69 63 61 74 69  this specificati
12110 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  on..**.** xSize 
12120 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
12130 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
12140 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
12150 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
12160 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
12170 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
12180 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
12190 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
121a0 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
121b0 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
121c0 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
121d0 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
121e0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
121f0 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
12200 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
12210 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
12220 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
12230 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12240 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
12250 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
12260 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
12270 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
12280 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
12290 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
122a0 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
122b0 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
122c0 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
122d0 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
122e0 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
122f0 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
12300 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
12310 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
12320 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
12330 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
12340 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
12350 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
12360 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
12370 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
12380 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
12390 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
123a0 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
123b0 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
123c0 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
123d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
123e0 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
123f0 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
12400 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20  llocator.  (For 
12410 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
12420 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
12430 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
12440 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
12450 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
12460 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
12470 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
12480 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
12490 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
124a0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
124b0 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
124c0 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
124d0 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
124e0 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
124f0 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
12500 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
12510 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
12520 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
12530 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
12540 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
12550 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
12560 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
12570 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
12580 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
12590 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
125a0 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
125b0 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
125c0 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
125d0 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
125e0 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
125f0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
12600 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
12610 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
12620 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
12630 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
12640 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
12650 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
12660 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
12670 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
12680 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
12690 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
126a0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
126b0 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
126c0 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
126d0 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
126e0 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
126f0 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
12700 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
12710 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
12720 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
12730 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
12740 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
12750 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
12760 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
12770 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
12780 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
12790 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
127a0 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
127b0 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
127c0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
127d0 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
127e0 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
127f0 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
12800 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
12810 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
12820 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
12830 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
12840 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
12850 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
12860 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
12870 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
12880 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
12890 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
128a0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
128b0 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
128c0 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
128d0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
128e0 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
128f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
12900 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
12910 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
12920 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
12930 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
12940 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
12950 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
12960 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
12970 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
12980 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
12990 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
129a0 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
129b0 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
129c0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
129d0 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
129e0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
129f0 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
12a00 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12a10 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
12a20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
12a30 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
12a40 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
12a50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
12a60 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
12a70 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
12a80 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
12a90 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
12aa0 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
12ab0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12ac0 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
12ad0 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
12ae0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
12af0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
12b00 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
12b10 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
12b20 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
12b30 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
12b40 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
12b50 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12b60 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
12b70 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
12b80 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
12b90 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
12ba0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
12bb0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
12bc0 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
12bd0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
12be0 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
12bf0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
12c00 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
12c10 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
12c20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
12c30 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
12c40 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
12c50 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
12c60 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
12c70 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
12c80 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
12c90 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
12ca0 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
12cb0 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
12cc0 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
12cd0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
12ce0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
12cf0 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
12d00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
12d10 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
12d20 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
12d30 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
12d40 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
12d50 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
12d60 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
12d70 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
12d80 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
12d90 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
12da0 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
12db0 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
12dc0 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
12dd0 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
12de0 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
12df0 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
12e00 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
12e10 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
12e20 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12e30 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
12e40 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
12e50 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
12e60 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
12e70 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
12e80 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
12e90 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12ea0 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
12eb0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
12ec0 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
12ed0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
12ee0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
12ef0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
12f00 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
12f10 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
12f20 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
12f30 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
12f40 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
12f50 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
12f60 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
12f70 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
12f80 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
12f90 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
12fa0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
12fb0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
12fc0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12fd0 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
12fe0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
12ff0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
13000 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
13010 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13020 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
13030 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
13040 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
13050 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
13060 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
13070 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
13080 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
13090 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
130a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
130b0 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
130c0 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
130d0 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
130e0 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
130f0 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
13100 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
13110 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
13120 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
13130 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
13140 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
13150 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
13160 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
13170 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
13180 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
13190 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
131a0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
131b0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
131c0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
131d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
131e0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
131f0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
13200 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
13210 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
13220 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
13230 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
13240 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
13250 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
13260 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
13270 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
13280 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
13290 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
132a0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
132b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
132c0 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
132d0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
132e0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
132f0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
13300 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
13310 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
13320 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
13330 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
13340 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
13350 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
13360 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
13370 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
13380 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
13390 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
133a0 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
133b0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
133c0 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
133d0 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
133e0 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
133f0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13400 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
13410 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
13420 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
13430 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
13440 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
13450 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
13460 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
13470 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
13480 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
13490 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
134a0 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
134b0 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
134c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
134d0 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
134e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
134f0 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
13500 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
13510 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
13520 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
13530 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
13540 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
13550 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
13560 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
13570 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
13580 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
13590 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
135a0 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
135b0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
135c0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
135d0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
135e0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
135f0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
13600 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
13610 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
13620 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
13630 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
13640 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
13650 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
13660 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13670 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13680 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13690 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
136a0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
136b0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
136c0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
136d0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
136e0 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
136f0 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
13700 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
13710 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13720 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
13730 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
13740 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
13750 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
13760 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
13770 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
13780 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
13790 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
137a0 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
137b0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
137c0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
137d0 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
137e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
137f0 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
13800 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
13810 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13820 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
13830 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
13840 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
13850 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
13860 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
13870 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
13880 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13890 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
138a0 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
138b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
138c0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
138d0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
138e0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
138f0 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
13900 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
13910 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
13920 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
13930 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
13940 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
13950 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
13960 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
13970 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
13980 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
13990 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
139a0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
139b0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
139c0 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
139d0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
139e0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
139f0 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  S</dt>.** <dd> ^
13a00 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
13a10 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
13a20 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69  t of type int, i
13a30 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
13a40 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  .** boolean, whi
13a50 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
13a60 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
13a70 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20  ction of memory 
13a80 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73  allocation .** s
13a90 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65  tatistics. ^(Whe
13aa0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
13ab0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
13ac0 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  re disabled, the
13ad0 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   .** following S
13ae0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
13af0 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
13b00 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
13b10 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
13b20 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
13b30 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
13b40 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
13b50 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
13b60 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
13b70 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
13b80 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
13b90 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
13ba0 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
13bb0 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
13bc0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
13bd0 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
13be0 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
13bf0 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
13c00 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
13c10 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
13c20 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
13c30 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
13c40 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
13c50 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
13c60 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
13c70 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
13c80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
13c90 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
13ca0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
13cb0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
13cc0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
13cd0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
13ce0 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
13cf0 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
13d00 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
13d10 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
13d20 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
13d30 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
13d40 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
13d50 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
13d60 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
13d70 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
13d80 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
13d90 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
13da0 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
13db0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
13dc0 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13dd0 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
13de0 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
13df0 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
13e00 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
13e10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
13e20 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
13e30 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
13e40 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
13e50 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
13e60 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
13e70 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
13e80 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
13e90 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
13ea0 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
13eb0 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
13ec0 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
13ed0 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
13ee0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
13ef0 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
13f00 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
13f10 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
13f20 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
13f30 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
13f40 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
13f50 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
13f60 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
13f70 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
13f80 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
13f90 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
13fa0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
13fb0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
13fc0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
13fd0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13fe0 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
13ff0 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
14000 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
14010 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
14020 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
14030 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
14040 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
14050 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
14060 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
14070 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
14080 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64  use for.** the d
14090 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
140a0 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
140b0 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ult page cache i
140c0 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a  mplemenation.  .
140d0 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
140e0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
140f0 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
14100 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
14110 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
14120 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
14130 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
14140 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14150 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a  _PCACHE option..
14160 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
14170 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
14180 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70  this option: A p
14190 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65  ointer to 8-byte
141a0 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f   aligned.** memo
141b0 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
141c0 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
141d0 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
141e0 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
141f0 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
14200 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
14210 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
14220 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
14230 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
14240 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
14250 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29  n 512 and 32768)
14260 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65   plus a little e
14270 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a  xtra for each.**
14280 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e   page header.  ^
14290 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20  The page header 
142a0 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30  size is 20 to 40
142b0 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67   bytes depending
142c0 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20   on.** the host 
142d0 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e  architecture.  ^
142e0 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
142f0 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
14300 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
14310 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69   to make sz a li
14320 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20  ttle too large. 
14330 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
14340 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
14350 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
14360 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
14370 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
14380 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
14390 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d  e will use the m
143a0 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62  emory provided b
143b0 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
143c0 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20  ment to satisfy 
143d0 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65  its.** memory ne
143e0 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73  eds for the firs
143f0 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69  t N pages that i
14400 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e  t adds to cache.
14410 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c    ^If additional
14420 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
14430 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
14440 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
14450 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
14460 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
14470 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
14480 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14490 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
144a0 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
144b0 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  ce..** The point
144c0 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
144d0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a  argument must.**
144e0 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
144f0 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
14500 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
14510 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
14520 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e  te.** will be un
14530 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
14540 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
14550 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
14560 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
14570 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
14580 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
14590 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
145a0 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f  e will use.** fo
145b0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
145c0 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
145d0 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79  cation needs bey
145e0 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
145f0 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51  ed.** for by [SQ
14600 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
14610 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  TCH] and [SQLITE
14620 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14630 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  E]..** There are
14640 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
14650 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  : An 8-byte alig
14660 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
14670 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
14680 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
14690 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
146a0 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
146b0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
146c0 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
146d0 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
146e0 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
146f0 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
14700 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
14710 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
14720 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
14730 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
14740 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
14750 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
14760 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
14770 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
14780 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
14790 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
147a0 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
147b0 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
147c0 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20  NULL and either 
147d0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
147e0 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53  EMSYS3] or.** [S
147f0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
14800 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65  SYS5] are define
14810 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  d, then the alte
14820 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
14830 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
14840 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
14850 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
14860 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14870 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
14880 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
14890 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
148a0 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
148b0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
148c0 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
148d0 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
148e0 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
148f0 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a  l be undefined..
14900 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61  ** The minimum a
14910 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69  llocation size i
14920 73 20 63 61 70 70 65 64 20 61 74 20 32 5e 31 32  s capped at 2^12
14930 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c  . Reasonable val
14940 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ues.** for the m
14950 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
14960 6e 20 73 69 7a 65 20 61 72 65 20 32 5e 35 20 74  n size are 2^5 t
14970 68 72 6f 75 67 68 20 32 5e 38 2e 3c 2f 64 64 3e  hrough 2^8.</dd>
14980 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
14990 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
149a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
149b0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
149c0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
149d0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
149e0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
149f0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
14a00 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14a10 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
14a20 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
14a30 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
14a40 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
14a50 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
14a60 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
14a70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
14a80 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
14a90 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
14aa0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
14ab0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
14ac0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
14ad0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
14ae0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
14af0 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
14b00 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
14b10 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
14b20 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
14b30 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
14b40 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
14b50 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
14b60 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
14b70 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14b80 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
14b90 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
14ba0 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
14bb0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
14bc0 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
14bd0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
14be0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
14bf0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
14c00 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
14c10 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
14c20 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
14c30 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
14c40 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
14c50 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14c60 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
14c70 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
14c80 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14c90 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
14ca0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
14cb0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
14cc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
14cd0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
14ce0 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
14cf0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14d00 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
14d10 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
14d20 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
14d30 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
14d40 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
14d50 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
14d60 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
14d70 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
14d80 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
14d90 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
14da0 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
14db0 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
14dc0 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
14dd0 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
14de0 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
14df0 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
14e00 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
14e10 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
14e20 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14e30 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
14e40 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
14e50 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
14e60 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
14e70 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
14e80 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
14e90 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
14ea0 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
14eb0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14ec0 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
14ed0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14ee0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
14ef0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
14f00 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
14f10 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
14f20 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
14f30 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
14f40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14f50 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
14f60 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
14f70 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
14f80 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
14f90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
14fa0 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  or the lookaside
14fb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
14fc0 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61  r on each.** [da
14fd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14fe0 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  n].  The first a
14ff0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
15000 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
15010 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
15020 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
15030 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
15040 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
15050 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
15060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15070 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f  ion.)^  ^(This o
15080 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
15090 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
150a0 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
150b0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
150c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
150d0 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c  .** verb to [sql
150e0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
150f0 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
15100 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
15110 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
15120 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
15130 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
15140 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
15150 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15160 47 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  G_PCACHE</dt>.**
15170 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
15180 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15190 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
151a0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
151b0 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33  o.** an [sqlite3
151c0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d  _pcache_methods]
151d0 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
151e0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20  bject specifies 
151f0 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
15200 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
15210 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
15220 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69  tation.)^  ^SQLi
15230 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
15240 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74  of the.** object
15250 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72   and uses it for
15260 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
15270 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c  ry allocations.<
15280 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
15290 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
152a0 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  PCACHE</dt>.** <
152b0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
152c0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
152d0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
152e0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
152f0 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  an.** [sqlite3_p
15300 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f  cache_methods] o
15310 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
15320 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72  opies of the cur
15330 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63  rent.** page cac
15340 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
15350 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
15360 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
15370 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15380 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
15390 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
153a0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
153b0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
153c0 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
153d0 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
153e0 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
153f0 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
15400 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
15410 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
15420 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
15430 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
15440 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
15450 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
15460 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
15470 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
15480 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
15490 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
154a0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
154b0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
154c0 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
154d0 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
154e0 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
154f0 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
15500 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
15510 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
15520 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
15530 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
15540 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
15550 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
15560 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
15570 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
15580 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
15590 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
155a0 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
155b0 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
155c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
155d0 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
155e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
155f0 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
15600 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
15610 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
15620 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
15630 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
15640 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
15650 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
15660 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
15670 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
15680 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
15690 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
156a0 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
156b0 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
156c0 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
156d0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
156e0 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
156f0 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
15700 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
15710 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
15720 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
15730 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
15740 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
15750 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
15760 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
15770 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
15780 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
15790 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
157a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
157b0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
157c0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
157d0 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
157e0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
157f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
15800 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
15810 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
15820 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15830 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
15840 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
15850 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15860 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
15870 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
15880 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15890 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
158a0 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
158b0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
158c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
158d0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
158e0 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
158f0 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
15900 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15910 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
15920 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
15930 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
15940 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15950 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
15960 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
15970 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
15980 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15990 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
159a0 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
159b0 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
159c0 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
159d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
159e0 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
159f0 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
15a00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15a10 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
15a20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
15a30 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
15a40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15a50 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
15a60 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
15a70 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
15a80 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
15a90 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
15aa0 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
15ab0 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
15ac0 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
15ad0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15ae0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
15af0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
15b00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15b10 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
15b20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65     14  /* sqlite
15b30 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15b40 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
15b50 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15b60 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73  ACHE    15  /* s
15b70 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
15b80 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
15b90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15ba0 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
15bb0 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
15bc0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
15bd0 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
15be0 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
15bf0 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
15c00 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
15c10 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
15c20 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
15c30 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15c40 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
15c50 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
15c60 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
15c70 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
15c80 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
15c90 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
15ca0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
15cb0 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
15cc0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
15cd0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
15ce0 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
15cf0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15d00 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
15d10 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
15d20 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
15d30 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
15d40 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
15d50 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
15d60 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
15d70 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
15d80 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
15d90 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
15da0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
15db0 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
15dc0 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
15dd0 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
15de0 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
15df0 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
15e00 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
15e10 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
15e20 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
15e30 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
15e40 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
15e50 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
15e60 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
15e70 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
15e80 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
15e90 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
15ea0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
15eb0 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
15ec0 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
15ed0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
15ee0 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
15ef0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
15f00 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
15f10 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
15f20 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
15f30 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
15f40 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
15f50 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
15f60 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
15f70 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15f80 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
15f90 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
15fa0 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
15fb0 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
15fc0 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
15fd0 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
15fe0 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
15ff0 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
16000 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
16010 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
16020 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
16030 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
16040 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
16050 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
16060 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
16070 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
16080 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
16090 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
160a0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
160b0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
160c0 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
160d0 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
160e0 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
160f0 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
16100 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
16110 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
16120 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
16130 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
16140 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
16150 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
16160 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16170 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
16180 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
16190 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
161a0 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
161b0 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
161c0 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
161d0 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
161e0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
161f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
16200 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
16210 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
16220 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
16230 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
16240 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
16250 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
16260 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
16270 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
16280 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
16290 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
162a0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
162b0 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
162c0 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
162d0 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
162e0 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
162f0 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
16300 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
16310 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
16320 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
16330 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
16340 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
16350 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
16360 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
16370 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
16380 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
16390 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
163a0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
163b0 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
163c0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
163d0 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
163e0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
163f0 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
16400 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
16410 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
16420 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
16430 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
16440 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
16450 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16460 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
16470 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
16480 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
16490 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
164a0 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
164b0 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
164c0 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
164d0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
164e0 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
164f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16500 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16510 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
16520 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
16530 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
16540 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
16550 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
16560 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
16570 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
16580 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
16590 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
165a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
165b0 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
165c0 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
165d0 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
165e0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
165f0 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
16600 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
16610 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
16620 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
16630 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
16640 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
16650 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
16660 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
16670 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
16680 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
16690 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
166a0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
166b0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
166c0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
166d0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
166e0 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
166f0 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
16700 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
16710 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
16720 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
16730 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
16740 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
16750 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
16760 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
16770 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
16780 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
16790 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
167a0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
167b0 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
167c0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
167d0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
167e0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
167f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
16800 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
16810 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
16820 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
16830 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
16840 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
16850 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
16860 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16870 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20         1001  /* 
16880 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
16890 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
168a0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
168b0 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f  FKEY     1002  /
168c0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
168d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
168e0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
168f0 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69  GGER  1003  /* i
16900 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
16910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
16920 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
16930 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
16940 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  odes.**.** ^The 
16950 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
16960 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
16970 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
16980 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
16990 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
169a0 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
169b0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
169c0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
169d0 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
169e0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
169f0 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
16a00 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
16a10 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
16a20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
16a30 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
16a40 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
16a50 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
16a60 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
16a70 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
16a80 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
16a90 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
16aa0 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
16ab0 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
16ac0 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
16ad0 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
16ae0 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
16af0 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
16b00 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
16b10 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
16b20 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
16b30 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
16b40 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
16b50 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
16b60 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
16b70 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
16b80 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
16b90 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
16ba0 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
16bb0 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
16bc0 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
16bd0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
16be0 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
16bf0 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
16c00 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
16c10 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
16c20 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
16c30 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
16c40 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
16c50 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
16c60 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
16c70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
16c80 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
16c90 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20  gument.  ^If no 
16ca0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
16cb0 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  RT]s.** have eve
16cc0 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
16cd0 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  at database conn
16ce0 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
16cf0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
16d00 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
16d10 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
16d20 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
16d30 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
16d40 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
16d50 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  w is returned by
16d60 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73   this routine as
16d70 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
16d80 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gger is running.
16d90 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
16da0 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61   trigger termina
16db0 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  tes, the value r
16dc0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
16dd0 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72  routine.** rever
16de0 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76  ts to the last v
16df0 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65  alue inserted be
16e00 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
16e10 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20   fired.)^.**.** 
16e20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
16e30 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
16e40 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
16e50 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
16e60 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
16e70 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
16e80 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
16e90 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
16ea0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
16eb0 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
16ec0 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
16ed0 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
16ee0 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
16ef0 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
16f00 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
16f10 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
16f20 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
16f30 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
16f40 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
16f50 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
16f60 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
16f70 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
16f80 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
16f90 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
16fa0 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
16fb0 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
16fc0 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
16fd0 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
16fe0 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
16ff0 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
17000 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
17010 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
17020 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
17030 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
17040 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
17050 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
17060 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
17070 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
17080 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
17090 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
170a0 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
170b0 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
170c0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
170d0 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
170e0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
170f0 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
17100 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
17110 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
17120 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
17130 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
17140 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
17150 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
17160 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
17170 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
17180 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17190 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
171a0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
171b0 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
171c0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
171d0 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
171e0 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
171f0 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
17200 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
17210 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
17220 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
17230 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
17240 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
17250 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
17260 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
17270 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
17280 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
17290 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
172a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
172b0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
172c0 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
172d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
172e0 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
172f0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
17300 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
17310 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
17320 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
17330 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
17340 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
17350 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
17360 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
17370 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
17380 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
17390 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
173a0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
173b0 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
173c0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
173d0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28  parameter..** ^(
173e0 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
173f0 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
17400 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
17410 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
17420 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
17430 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
17440 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
17450 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
17460 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
17470 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b  rs or [foreign k
17480 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
17490 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55  not counted.)^ U
174a0 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
174b0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
174c0 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ()] function to 
174d0 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e  find the total n
174e0 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
174f0 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  .** including ch
17500 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
17510 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72  triggers and for
17520 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
17530 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  ..**.** ^Changes
17540 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
17550 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79  are simulated by
17560 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
17570 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20  trigger].** are 
17580 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e  not counted.  On
17590 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68  ly real table ch
175a0 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
175b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f  d..**.** ^(A "ro
175c0 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
175d0 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
175e0 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
175f0 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
17600 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
17610 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
17620 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
17630 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
17640 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
17650 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41  ffects of [REPLA
17660 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
17670 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f  esolution,.** ro
17680 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72  llback, ABORT pr
17690 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20  ocessing, [DROP 
176a0 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e  TABLE], or by an
176b0 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
176c0 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
176d0 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
176e0 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a   changes.)^.**.*
176f0 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
17700 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
17710 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
17720 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
17730 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
17740 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41  cript of a [CREA
17750 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
17760 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20  gger]. .** Most 
17770 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
17780 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
17790 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
177a0 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
177b0 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
177c0 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
177d0 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
177e0 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
177f0 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
17800 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
17810 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
17820 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
17830 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
17840 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
17850 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
17860 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
17870 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
17880 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71  .** ^Calling [sq
17890 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
178a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
178b0 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f  ] recursively do
178c0 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65  es.** not create
178d0 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63   a new trigger c
178e0 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
178f0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
17900 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
17910 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
17920 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
17930 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
17940 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
17950 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
17960 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
17970 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
17980 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c  xt..**.** ^Thus,
17990 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
179a0 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
179b0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
179c0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
179d0 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
179e0 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
179f0 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
17a00 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
17a10 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
17a20 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
17a30 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74  vel.  ^(Within t
17a40 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
17a50 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
17a60 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
17a70 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
17a80 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
17a90 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
17aa0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
17ab0 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
17ac0 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
17ad0 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
17ae0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
17af0 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
17b00 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
17b10 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
17b20 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
17b30 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
17b40 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
17b50 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
17b60 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
17b70 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
17b80 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a  context.)^.**.**
17b90 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
17ba0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
17bb0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
17bc0 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
17bd0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
17be0 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
17bf0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
17c00 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
17c10 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
17c20 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
17c30 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
17c40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
17c50 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
17c60 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
17c70 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
17c80 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
17c90 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
17ca0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
17cb0 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
17cc0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
17cd0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
17ce0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17cf0 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
17d00 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
17d10 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
17d20 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
17d30 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
17d40 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
17d50 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b  y [INSERT],.** [
17d60 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
17d70 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73  TE] statements s
17d80 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
17d90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
17da0 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28  as opened..** ^(
17db0 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  The count return
17dc0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
17dd0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  tal_changes() in
17de0 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
17df0 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b  es.** from all [
17e00 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
17e10 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
17e20 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d  ts and changes m
17e30 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69  ade by.** [forei
17e40 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e  gn key actions].
17e50 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
17e60 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
17e70 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
17e80 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
17e90 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  t [REPLACE] cons
17ea0 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72  traints,.** do r
17eb0 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
17ec0 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72  T processing, or
17ed0 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72   [DROP TABLE] pr
17ee0 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a  ocessing.  The.*
17ef0 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  * count does not
17f00 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66   include rows of
17f10 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65   views that fire
17f20 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
17f30 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f  trigger],.** tho
17f40 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45  ugh if the INSTE
17f50 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61  AD OF trigger ma
17f60 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69  kes changes of i
17f70 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68  ts own, those ch
17f80 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f  anges .** are co
17f90 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65  unted.)^.** ^The
17fa0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
17fb0 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
17fc0 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61  n counts the cha
17fd0 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a  nges as soon as.
17fe0 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
17ff0 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
18000 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
18010 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
18020 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70  t handle.** is p
18030 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
18040 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
18050 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
18060 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
18070 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
18080 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
18090 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
180a0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
180b0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
180c0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
180d0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
180e0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
180f0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
18100 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
18110 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
18120 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
18130 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
18140 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
18150 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
18160 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
18170 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
18180 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
18190 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
181a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
181b0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
181c0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
181d0 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
181e0 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
181f0 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
18200 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
18210 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
18220 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
18230 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
18240 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
18250 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
18260 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
18270 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
18280 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
18290 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
182a0 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
182b0 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
182c0 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
182d0 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
182e0 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
182f0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
18300 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
18310 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
18320 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
18330 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
18340 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
18350 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
18360 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
18370 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
18380 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
18390 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
183a0 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
183b0 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
183c0 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
183d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
183e0 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
183f0 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
18400 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
18410 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
18420 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
18430 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
18440 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
18450 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
18460 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
18470 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
18480 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
18490 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
184a0 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
184b0 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
184c0 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
184d0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
184e0 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
184f0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
18500 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
18510 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
18520 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
18530 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
18540 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
18550 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
18560 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
18570 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
18580 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
18590 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
185a0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
185b0 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
185c0 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
185d0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
185e0 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
185f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18600 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
18610 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
18620 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
18630 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
18640 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
18650 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
18660 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
18670 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
18680 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
18690 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
186a0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
186b0 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
186c0 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
186d0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
186e0 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
186f0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
18700 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
18710 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
18720 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
18730 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
18740 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
18750 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
18760 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
18770 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
18780 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
18790 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
187a0 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
187b0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
187c0 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
187d0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
187e0 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
187f0 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
18800 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
18810 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
18820 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
18830 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
18840 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
18850 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
18860 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
18870 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
18880 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
18890 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
188a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
188b0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
188c0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
188d0 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
188e0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
188f0 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
18900 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53  ely happen..*/.S
18910 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
18920 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18930 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
18940 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
18950 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
18960 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
18970 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
18980 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
18990 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
189a0 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
189b0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
189c0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
189d0 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
189e0 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
189f0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
18a00 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
18a10 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
18a20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
18a30 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
18a40 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
18a50 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
18a60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
18a70 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
18a80 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
18a90 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
18aa0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
18ab0 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
18ac0 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
18ad0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
18ae0 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
18af0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
18b00 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
18b10 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
18b20 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
18b30 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
18b40 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
18b50 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
18b60 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
18b70 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
18b80 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
18b90 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
18ba0 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
18bb0 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
18bc0 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
18bd0 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
18be0 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
18bf0 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
18c00 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
18c10 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
18c20 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
18c30 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
18c40 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
18c50 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
18c60 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
18c70 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
18c80 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
18c90 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
18ca0 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
18cb0 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
18cc0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
18cd0 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
18ce0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
18cf0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
18d00 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
18d10 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
18d20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
18d30 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
18d40 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
18d50 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
18d60 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
18d70 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
18d80 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
18d90 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
18da0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
18db0 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
18dc0 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
18dd0 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
18de0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
18df0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
18e00 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
18e10 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
18e20 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
18e30 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
18e40 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
18e50 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
18e60 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
18e70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
18e80 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
18e90 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
18ea0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
18eb0 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
18ec0 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
18ed0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
18ee0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
18ef0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
18f00 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
18f10 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
18f20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
18f30 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
18f40 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
18f50 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
18f60 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
18f70 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
18f80 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  der..*/.SQLITE_A
18f90 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
18fa0 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
18fb0 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45  ar *sql);.SQLITE
18fc0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
18fd0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
18fe0 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
18ff0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
19000 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
19010 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
19020 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
19030 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
19040 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
19050 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
19060 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
19070 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
19080 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
19090 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
190a0 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
190b0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
190c0 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
190d0 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
190e0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
190f0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
19100 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
19110 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
19120 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
19130 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
19140 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
19150 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
19160 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
19170 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
19180 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
19190 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
191a0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
191b0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
191c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
191d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
191e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
191f0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
19200 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
19210 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
19220 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
19230 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
19240 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
19250 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
19260 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
19270 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
19280 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
19290 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
192a0 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
192b0 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
192c0 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
192d0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
192e0 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
192f0 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
19300 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
19310 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
19320 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
19330 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
19340 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
19350 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
19360 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
19370 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
19380 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
19390 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
193a0 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
193b0 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
193c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
193d0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
193e0 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
193f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
19400 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
19410 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
19420 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
19430 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
19440 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
19450 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
19460 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
19470 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
19480 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
19490 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
194a0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
194b0 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
194c0 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
194d0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
194e0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
194f0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
19500 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
19510 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
19520 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
19530 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
19540 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
19550 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
19560 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
19570 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
19580 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
19590 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
195a0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
195b0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
195c0 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
195d0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
195e0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
195f0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
19600 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
19610 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
19620 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
19630 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
19640 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
19650 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
19660 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
19670 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
19680 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
19690 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
196a0 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
196b0 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
196c0 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
196d0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
196e0 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
196f0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
19700 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
19710 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
19720 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
19730 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
19740 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
19750 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
19760 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
19770 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
19780 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
19790 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
197a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
197b0 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
197c0 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
197d0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
197e0 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
197f0 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
19800 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
19810 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
19820 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
19830 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
19840 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
19850 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
19860 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
19870 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
19880 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
19890 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
198a0 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
198b0 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
198c0 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
198d0 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
198e0 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
198f0 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
19900 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
19910 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
19920 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
19930 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
19940 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
19950 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
19960 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
19970 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
19980 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
19990 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
199a0 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
199b0 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
199c0 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
199d0 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
199e0 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
199f0 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
19a00 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
19a10 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
19a20 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
19a30 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
19a40 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
19a50 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
19a60 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
19a70 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
19a80 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
19a90 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
19aa0 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
19ab0 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
19ac0 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
19ad0 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
19ae0 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
19af0 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
19b00 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
19b10 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
19b20 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
19b30 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
19b40 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
19b50 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
19b60 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
19b70 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
19b80 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
19b90 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
19ba0 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
19bb0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
19bc0 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
19bd0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
19be0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
19bf0 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
19c00 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
19c10 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
19c20 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
19c30 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
19c40 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
19c50 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
19c60 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
19c70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19c80 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
19c90 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19ca0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
19cb0 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
19cc0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
19cd0 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
19ce0 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
19cf0 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
19d00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19d10 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
19d20 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
19d30 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
19d40 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53  sy handler..*/.S
19d50 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
19d60 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
19d70 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
19d80 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
19d90 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
19da0 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
19db0 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a  usy Timeout.**.*
19dc0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
19dd0 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
19de0 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
19df0 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
19e00 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
19e10 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
19e20 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
19e30 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
19e40 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
19e50 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
19e60 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
19e70 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
19e80 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
19e90 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
19ea0 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
19eb0 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
19ec0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
19ed0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
19ee0 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
19ef0 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
19f00 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
19f10 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
19f20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
19f30 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
19f40 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
19f50 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
19f60 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
19f70 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
19f80 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
19f90 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
19fa0 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
19fb0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
19fc0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
19fd0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
19fe0 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
19ff0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1a000 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1a010 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  ny any given mom
1a020 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
1a030 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
1a040 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
1a050 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
1a060 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
1a070 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
1a080 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
1a090 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
1a0a0 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
1a0b0 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  red.)^.*/.SQLITE
1a0c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1a0d0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
1a0e0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
1a0f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a100 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
1a110 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
1a120 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
1a130 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
1a140 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1a150 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
1a160 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1a170 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
1a180 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
1a190 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
1a1a0 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
1a1b0 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
1a1c0 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
1a1d0 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
1a1e0 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
1a1f0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
1a200 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1a210 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
1a220 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
1a230 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
1a240 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
1a250 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
1a260 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
1a270 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
1a280 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
1a290 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
1a2a0 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
1a2b0 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
1a2c0 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
1a2d0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1a2e0 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
1a2f0 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
1a300 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
1a310 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
1a320 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1a330 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
1a340 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1a350 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
1a360 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
1a370 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
1a380 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
1a390 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1a3a0 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
1a3b0 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
1a3c0 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
1a3d0 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1a3e0 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1a3f0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1a400 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1a410 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1a420 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1a430 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1a440 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1a450 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1a460 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1a470 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1a480 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1a490 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1a4a0 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1a4b0 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1a4c0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1a4d0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1a4e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1a4f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1a500 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1a510 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1a520 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1a530 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1a540 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1a550 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1a560 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1a570 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1a580 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1a590 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1a5a0 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1a5b0 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1a5c0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1a5d0 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1a5e0 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1a5f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1a600 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1a610 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1a620 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1a630 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1a640 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1a650 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1a660 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1a670 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1a680 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1a690 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1a6a0 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1a6b0 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1a6c0 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1a6d0 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1a6e0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1a6f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1a700 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1a710 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1a720 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1a730 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1a740 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1a750 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1a760 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1a770 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1a780 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1a790 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1a7a0 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1a7b0 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1a7c0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1a7d0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
1a7e0 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1a7f0 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1a800 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1a810 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1a820 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a830 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1a840 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a850 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1a860 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a870 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1a880 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a890 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1a8a0 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1a8b0 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1a8c0 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1a8d0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1a8e0 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1a8f0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1a900 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1a910 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a920 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1a930 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1a940 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1a950 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1a960 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1a970 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1a980 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1a990 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1a9a0 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1a9b0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1a9c0 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1a9d0 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1a9e0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1a9f0 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1aa00 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1aa10 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1aa20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1aa30 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1aa40 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1aa50 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1aa60 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1aa70 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1aa80 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1aa90 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1aaa0 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1aab0 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1aac0 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1aad0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1aae0 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1aaf0 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1ab00 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1ab10 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1ab20 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1ab30 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1ab40 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1ab50 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1ab60 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1ab70 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1ab80 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1ab90 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1aba0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1abb0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1abc0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1abd0 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1abe0 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1abf0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1ac00 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1ac10 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1ac20 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1ac30 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1ac40 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1ac50 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1ac60 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1ac70 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1ac80 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1ac90 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1aca0 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1acb0 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1acc0 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1acd0 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1ace0 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1acf0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1ad00 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1ad10 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1ad20 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1ad30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1ad40 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1ad50 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1ad60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1ad70 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
1ad80 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1ad90 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1ada0 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1adb0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1adc0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1add0 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1ade0 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1adf0 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1ae00 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1ae10 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1ae20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1ae30 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1ae40 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1ae50 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1ae60 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1ae70 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1ae80 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1ae90 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1aea0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1aeb0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1aec0 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1aed0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
1aee0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  I void sqlite3_f
1aef0 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1af00 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1af10 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1af20 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1af30 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1af40 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1af50 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1af60 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1af70 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1af80 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1af90 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1afa0 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
1afb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1afc0 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1afd0 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1afe0 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1aff0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1b000 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1b010 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1b020 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1b030 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1b040 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1b050 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1b060 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1b070 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1b080 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1b090 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1b0a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1b0b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1b0c0 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1b0d0 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1b0e0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1b0f0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1b100 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1b110 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1b120 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1b130 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1b140 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1b150 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1b160 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1b170 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1b180 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1b190 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1b1a0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1b1b0 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1b1c0 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1b1d0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1b1e0 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1b1f0 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1b200 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1b210 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1b220 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1b230 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1b240 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1b250 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1b260 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1b270 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1b280 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1b290 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1b2a0 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1b2b0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1b2c0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1b2d0 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1b2e0 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1b2f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1b300 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1b310 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1b320 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1b330 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1b340 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1b350 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1b360 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1b370 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1b380 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1b390 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1b3a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1b3b0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1b3c0 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1b3d0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1b3e0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1b3f0 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1b400 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1b410 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1b420 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1b430 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1b440 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1b450 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1b460 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1b470 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1b480 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1b490 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1b4a0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1b4b0 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1b4c0 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1b4d0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1b4e0 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1b4f0 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1b500 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1b510 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1b520 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1b530 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b540 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1b550 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1b560 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1b570 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1b580 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1b590 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1b5a0 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1b5b0 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1b5c0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1b5d0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1b5e0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1b5f0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1b600 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1b610 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1b620 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1b630 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1b640 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1b650 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
1b660 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1b670 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1b680 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1b690 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1b6a0 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74  titutes a null-t
1b6b0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1b6c0 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
1b6d0 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
1b6e0 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
1b6f0 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
1b700 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
1b710 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
1b720 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
1b730 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20   literal.)^  By 
1b740 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
1b750 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
1b760 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
1b770 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
1b780 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
1b790 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
1b7a0 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
1b7b0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
1b7c0 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
1b7d0 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
1b7e0 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
1b7f0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1b800 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1b810 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
1b820 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
1b830 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
1b840 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1b850 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
1b860 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
1b870 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1b880 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1b890 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1b8a0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1b8b0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1b8c0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1b8d0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
1b8e0 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
1b8f0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1b900 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1b910 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1b920 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1b930 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1b940 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
1b950 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
1b960 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
1b970 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
1b980 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
1b990 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
1b9a0 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
1b9b0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1b9c0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1b9d0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1b9e0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1b9f0 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
1ba00 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
1ba10 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1ba20 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
1ba30 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
1ba40 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
1ba50 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
1ba60 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
1ba70 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
1ba80 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
1ba90 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1baa0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1bab0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1bac0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1bad0 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
1bae0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1baf0 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
1bb00 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
1bb10 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
1bb20 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
1bb30 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
1bb40 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
1bb50 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
1bb60 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
1bb70 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
1bb80 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ral..**.** ^(The
1bb90 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
1bba0 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
1bbb0 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
1bbc0 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
1bbd0 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
1bbe0 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
1bbf0 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
1bc00 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
1bc10 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
1bc20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
1bc30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
1bc40 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
1bc50 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
1bc60 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
1bc70 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53  le quotes).)^  S
1bc80 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
1bc90 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
1bca0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1bcb0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1bcc0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1bcd0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1bce0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1bcf0 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
1bd00 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1bd10 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1bd20 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1bd30 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1bd40 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1bd50 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
1bd60 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
1bd70 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
1bd80 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1bd90 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
1bda0 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
1bdb0 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
1bdc0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1bdd0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  r..**.** ^(The "
1bde0 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
1bdf0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1be00 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
1be10 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
1be20 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
1be30 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
1be40 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
1be50 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
1be60 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1be70 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
1be80 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1be90 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
1bea0 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
1beb0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1bec0 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  ar*,...);.SQLITE
1bed0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1bee0 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1bef0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1bf00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1bf10 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
1bf20 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1bf30 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1bf40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1bf50 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
1bf60 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1bf70 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1bf80 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
1bf90 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1bfa0 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
1bfb0 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
1bfc0 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
1bfd0 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
1bfe0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
1bff0 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
1c000 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1c010 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
1c020 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
1c030 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
1c040 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
1c050 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
1c060 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
1c070 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1c080 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
1c090 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
1c0a0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1c0b0 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
1c0c0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
1c0d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c0e0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1c0f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1c100 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
1c110 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
1c120 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
1c130 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
1c140 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
1c150 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c160 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
1c170 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
1c180 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
1c190 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
1c1a0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
1c1b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
1c1c0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
1c1d0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1c1e0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
1c1f0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c200 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
1c210 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1c220 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
1c230 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
1c240 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
1c250 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
1c260 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1c270 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1c280 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
1c290 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
1c2a0 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
1c2b0 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
1c2c0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
1c2d0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
1c2e0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
1c2f0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1c300 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
1c310 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
1c320 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
1c330 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
1c340 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
1c350 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
1c360 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
1c370 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
1c380 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
1c390 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
1c3a0 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
1c3b0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
1c3c0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1c3d0 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
1c3e0 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
1c3f0 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
1c400 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
1c410 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
1c420 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
1c430 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
1c440 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1c450 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1c460 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
1c470 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
1c480 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
1c490 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c4a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1c4b0 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  loc()..**.** ^(T
1c4c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1c4d0 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  oc() interface a
1c4e0 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
1c4f0 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
1c500 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1c510 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
1c520 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69  bytes, where N i
1c530 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20  s the.** second 
1c540 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
1c550 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1c560 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20  n to be resized 
1c570 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
1c580 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49  parameter.)^ ^ I
1c590 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
1c5a0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1c5b0 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
1c5c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1c5d0 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
1c5e0 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
1c5f0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
1c600 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
1c610 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
1c620 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1c630 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1c640 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  c()..** ^If the 
1c650 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1c660 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1c670 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
1c680 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
1c690 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1c6a0 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
1c6b0 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
1c6c0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29   sqlite3_free(P)
1c6d0 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20   where P is the 
1c6e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1c6f0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1c700 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  oc()..** ^sqlite
1c710 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
1c720 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1c730 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1c740 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1c750 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1c760 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
1c770 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1c780 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
1c790 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1c7a0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1c7b0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1c7c0 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1c7d0 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1c7e0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1c7f0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1c800 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1c810 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1c820 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1c830 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70  lloc() and the p
1c840 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1c850 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  is freed..** ^If
1c860 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c870 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  () returns NULL,
1c880 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20   then the prior 
1c890 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
1c8a0 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
1c8b0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
1c8c0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1c8d0 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73  3_malloc() and s
1c8e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c8f0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
1c900 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
1c910 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
1c920 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a  dary, or to a.**
1c930 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   4 byte boundary
1c940 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1c950 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d  4_BYTE_ALIGNED_M
1c960 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74  ALLOC] compile-t
1c970 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73  ime.** option is
1c980 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20   used..**.** In 
1c990 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1c9a0 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
1c9b0 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
1c9c0 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
1c9d0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
1c9e0 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
1c9f0 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
1ca00 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
1ca10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1ca20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1ca30 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
1ca40 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
1ca50 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
1ca60 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
1ca70 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
1ca80 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
1ca90 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
1caa0 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  The Windows OS i
1cab0 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
1cac0 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74  alls.** the syst
1cad0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1cae0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1caf0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1cb00 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1cb10 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1cb20 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1cb30 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1cb40 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1cb50 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1cb60 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1cb70 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1cb80 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1cb90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1cba0 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74  rrors are detect
1cbb0 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
1cbc0 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  are reported bac
1cbd0 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
1cbe0 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
1cbf0 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
1cc00 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1cc10 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
1cc20 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
1cc30 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
1cc40 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
1cc50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1cc60 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
1cc70 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
1cc80 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
1cc90 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
1cca0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1ccb0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1ccc0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1ccd0 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
1cce0 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
1ccf0 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
1cd00 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1cd10 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
1cd20 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
1cd30 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
1cd40 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
1cd50 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
1cd60 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
1cd70 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1cd80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1cd90 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  loc()]..*/.SQLIT
1cda0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
1cdb0 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1cdc0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1cdd0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1cde0 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53  c(void*, int);.S
1cdf0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1ce00 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
1ce10 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1ce20 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1ce30 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
1ce40 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
1ce50 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
1ce60 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
1ce70 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
1ce80 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
1ce90 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
1cea0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
1ceb0 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
1cec0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1ced0 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
1cee0 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
1cef0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1cf00 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
1cf10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
1cf20 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1cf30 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
1cf40 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1cf50 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
1cf60 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
1cf70 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
1cf80 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
1cf90 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
1cfa0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1cfb0 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
1cfc0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
1cfd0 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
1cfe0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
1cff0 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
1d000 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1d010 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
1d020 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
1d030 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1d040 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1d050 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1d060 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1d070 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
1d080 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
1d090 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
1d0a0 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
1d0b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
1d0c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1d0d0 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
1d0e0 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
1d0f0 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
1d100 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
1d110 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
1d120 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
1d130 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
1d140 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1d150 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1d160 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
1d170 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
1d180 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
1d190 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
1d1a0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
1d1b0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1d1c0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1d1d0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
1d1e0 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
1d1f0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
1d200 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1d210 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
1d220 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
1d230 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
1d240 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
1d250 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1d260 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1d270 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1d280 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  d);.SQLITE_API s
1d290 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1d2a0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1d2b0 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
1d2c0 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
1d2d0 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
1d2e0 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
1d2f0 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
1d300 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
1d310 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
1d320 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
1d330 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
1d340 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
1d350 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
1d360 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
1d370 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
1d380 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
1d390 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
1d3a0 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
1d3b0 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
1d3c0 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
1d3d0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
1d3e0 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
1d3f0 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
1d400 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
1d410 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
1d420 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1d430 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
1d440 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
1d450 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
1d460 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
1d470 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
1d480 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
1d490 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
1d4a0 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
1d4b0 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fer P..**.** ^Th
1d4c0 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
1d4d0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
1d4e0 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
1d4f0 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
1d500 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1d510 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
1d520 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
1d530 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
1d540 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
1d550 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
1d560 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1d570 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1d580 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75  t..** ^On all su
1d590 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
1d5a0 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
1d5b0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1d5c0 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1d5d0 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1d5e0 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1d5f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1d600 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1d610 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54  method..*/.SQLIT
1d620 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1d630 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
1d640 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
1d650 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d660 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
1d670 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
1d680 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
1d690 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
1d6a0 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  rs an authorizer
1d6b0 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
1d6c0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1d6d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d6e0 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
1d6f0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
1d700 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
1d710 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d720 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
1d730 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
1d740 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
1d750 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1d760 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1d770 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
1d780 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d790 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1d7a0 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
1d7b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d7c0 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
1d7d0 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
1d7e0 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
1d7f0 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
1d800 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
1d810 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
1d820 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
1d830 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
1d840 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d850 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
1d860 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
1d870 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
1d880 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
1d890 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d8a0 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
1d8b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
1d8c0 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
1d8d0 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
1d8e0 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
1d8f0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
1d900 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
1d910 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1d920 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
1d930 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
1d940 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1d950 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
1d960 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
1d970 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
1d980 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
1d990 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
1d9a0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d9b0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
1d9c0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
1d9d0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1d9e0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
1d9f0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
1da00 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
1da10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1da20 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1da30 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1da40 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
1da50 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1da60 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1da70 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
1da80 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1da90 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1daa0 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
1dab0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
1dac0 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
1dad0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
1dae0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1daf0 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
1db00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1db10 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1db20 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1db30 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
1db40 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
1db50 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1db60 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
1db70 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
1db80 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
1db90 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
1dba0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1dbb0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1dbc0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
1dbd0 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
1dbe0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
1dbf0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
1dc00 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
1dc10 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
1dc20 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
1dc30 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1dc40 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1dc50 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1dc60 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
1dc70 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
1dc80 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
1dc90 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1dca0 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
1dcb0 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
1dcc0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
1dcd0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
1dce0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1dcf0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
1dd00 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
1dd10 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
1dd20 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
1dd30 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
1dd40 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
1dd50 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1dd60 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
1dd70 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1dd80 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
1dd90 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
1dda0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1ddb0 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
1ddc0 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
1ddd0 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
1dde0 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
1ddf0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
1de00 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
1de10 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
1de20 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
1de30 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
1de40 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1de50 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
1de60 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
1de70 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
1de80 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
1de90 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
1dea0 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
1deb0 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
1dec0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1ded0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
1dee0 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
1def0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1df00 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
1df10 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
1df20 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
1df30 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
1df40 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
1df50 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
1df60 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
1df70 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
1df80 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
1df90 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
1dfa0 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
1dfb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1dfc0 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
1dfd0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
1dfe0 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
1dff0 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
1e000 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
1e010 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
1e020 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
1e030 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
1e040 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
1e050 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
1e060 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
1e070 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
1e080 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
1e090 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
1e0a0 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
1e0b0 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
1e0c0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
1e0d0 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
1e0e0 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
1e0f0 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
1e100 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
1e110 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
1e120 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1e130 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
1e140 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
1e150 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
1e160 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
1e170 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1e180 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
1e190 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
1e1a0 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
1e1b0 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
1e1c0 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
1e1d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1e1e0 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
1e1f0 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
1e200 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
1e210 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
1e220 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
1e230 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1e240 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
1e250 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
1e260 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
1e270 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
1e280 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
1e290 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
1e2a0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1e2b0 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
1e2c0 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
1e2d0 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
1e2e0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
1e2f0 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
1e300 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
1e310 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
1e320 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
1e330 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
1e340 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
1e350 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
1e360 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
1e370 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
1e380 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
1e390 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
1e3a0 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
1e3b0 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
1e3c0 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
1e3d0 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
1e3e0 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
1e3f0 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
1e400 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
1e410 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
1e420 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1e430 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1e440 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1e450 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1e460 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1e470 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1e480 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
1e490 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e4a0 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
1e4b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e4c0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1e4d0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1e4e0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1e4f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1e500 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1e510 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1e520 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1e530 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
1e540 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e550 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
1e560 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
1e570 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
1e580 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
1e590 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
1e5a0 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
1e5b0 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
1e5c0 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
1e5d0 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
1e5e0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
1e5f0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1e600 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
1e610 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1e620 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
1e630 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
1e640 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1e650 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
1e660 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e670 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1e680 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
1e690 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e6a0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
1e6b0 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
1e6c0 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
1e6d0 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
1e6e0 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
1e6f0 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
1e700 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
1e710 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
1e720 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
1e730 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
1e740 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
1e750 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
1e760 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
1e770 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1e780 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
1e790 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54  change..*/.SQLIT
1e7a0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1e7b0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1e7c0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1e7d0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1e7e0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1e7f0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1e800 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1e810 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1e820 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1e830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1e840 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1e850 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1e860 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1e870 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1e880 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
1e890 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
1e8a0 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
1e8b0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
1e8c0 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
1e8d0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
1e8e0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
1e8f0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
1e900 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
1e910 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
1e920 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
1e930 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1e940 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
1e950 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1e960 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1e970 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
1e980 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e990 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
1e9a0 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
1e9b0 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
1e9c0 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
1e9d0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
1e9e0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
1e9f0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
1ea00 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
1ea10 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
1ea20 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1ea30 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
1ea40 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1ea50 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1ea60 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
1ea70 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
1ea80 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
1ea90 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
1eaa0 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
1eab0 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
1eac0 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
1ead0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1eae0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
1eaf0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1eb00 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
1eb10 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
1eb20 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
1eb30 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
1eb40 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
1eb50 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
1eb60 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
1eb70 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
1eb80 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
1eb90 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
1eba0 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
1ebb0 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
1ebc0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
1ebd0 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
1ebe0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
1ebf0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
1ec00 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
1ec10 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
1ec20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
1ec30 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
1ec40 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
1ec50 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
1ec60 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
1ec70 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1ec80 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
1ec90 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
1eca0 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
1ecb0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1ecc0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1ecd0 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
1ece0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
1ecf0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
1ed00 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
1ed10 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1ed20 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1ed30 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
1ed40 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
1ed50 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
1ed60 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
1ed70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
1ed80 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
1ed90 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
1eda0 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
1edb0 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
1edc0 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
1edd0 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
1ede0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1edf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ee00 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
1ee10 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
1ee20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
1ee30 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ee40 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1ee50 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
1ee60 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1ee70 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ee80 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ee90 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1eea0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1eeb0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1eec0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1eed0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1eee0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
1eef0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1ef00 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1ef10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ef20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1ef30 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
1ef40 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1ef50 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1ef60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ef70 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1ef80 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
1ef90 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1efa0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1efb0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1efc0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1efd0 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
1efe0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1eff0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f000 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f010 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
1f020 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
1f030 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1f040 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f050 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f060 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
1f070 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
1f080 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1f090 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f0a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f0b0 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
1f0c0 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
1f0d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1f0e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f0f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f100 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
1f110 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
1f120 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1f130 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f140 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f150 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
1f160 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
1f170 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1f180 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f190 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f1a0 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
1f1b0 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
1f1c0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1f1d0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1f1e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f1f0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
1f200 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
1f210 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f220 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f230 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f240 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
1f250 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
1f260 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1f270 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1f280 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f290 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1f2a0 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
1f2b0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1f2c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f2d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f2e0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
1f2f0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
1f300 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1f310 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f320 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1f330 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
1f340 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
1f350 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f360 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f370 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
1f380 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
1f390 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1f3a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f3b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f3c0 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
1f3d0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
1f3e0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
1f3f0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
1f400 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
1f410 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
1f420 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
1f430 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f440 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1f450 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f460 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
1f470 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
1f480 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1f490 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f4a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f4b0 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
1f4c0 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
1f4d0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1f4e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f4f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f500 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
1f510 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
1f520 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f530 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1f540 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f550 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
1f560 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
1f570 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
1f580 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f590 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f5a0 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
1f5b0 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
1f5c0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
1f5d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f5e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f5f0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
1f600 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
1f610 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
1f620 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f630 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f640 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
1f650 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
1f660 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
1f670 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f680 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1f690 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
1f6a0 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
1f6b0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1f6c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f6d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1f6e0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
1f6f0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
1f700 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1f710 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1f720 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f730 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
1f740 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
1f750 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1f760 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1f770 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
1f780 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
1f790 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
1f7a0 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
1f7b0 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
1f7c0 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
1f7d0 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
1f7e0 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
1f7f0 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
1f800 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
1f810 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
1f820 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f830 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
1f840 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
1f850 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
1f860 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
1f870 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1f880 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1f890 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
1f8a0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
1f8b0 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
1f8c0 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
1f8d0 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
1f8e0 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
1f8f0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1f900 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1f910 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1f920 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
1f930 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
1f940 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
1f950 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
1f960 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
1f970 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
1f980 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
1f990 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
1f9a0 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
1f9b0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
1f9c0 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
1f9d0 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
1f9e0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
1f9f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
1fa00 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
1fa10 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
1fa20 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
1fa30 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
1fa40 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
1fa50 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
1fa60 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
1fa70 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
1fa80 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
1fa90 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
1faa0 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
1fab0 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
1fac0 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
1fad0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
1fae0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1faf0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1fb00 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
1fb10 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
1fb20 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
1fb30 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
1fb40 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1fb50 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
1fb60 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
1fb70 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
1fb80 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
1fb90 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
1fba0 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
1fbb0 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
1fbc0 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
1fbd0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
1fbe0 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
1fbf0 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
1fc00 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
1fc10 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
1fc20 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
1fc30 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
1fc40 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
1fc50 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
1fc60 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
1fc70 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
1fc80 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
1fc90 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
1fca0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1fcb0 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
1fcc0 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
1fcd0 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
1fce0 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
1fcf0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
1fd00 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
1fd10 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
1fd20 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
1fd30 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
1fd40 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
1fd50 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1fd60 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
1fd70 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
1fd80 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
1fd90 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
1fda0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1fdb0 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
1fdc0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
1fdd0 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
1fde0 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
1fdf0 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
1fe00 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
1fe10 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1fe20 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
1fe30 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
1fe40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
1fe50 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
1fe60 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
1fe70 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1fe80 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
1fe90 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
1fea0 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
1feb0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
1fec0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
1fed0 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
1fee0 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
1fef0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
1ff00 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
1ff10 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
1ff20 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1ff30 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
1ff40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ff50 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
1ff60 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
1ff70 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
1ff80 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
1ff90 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
1ffa0 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
1ffb0 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
1ffc0 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
1ffd0 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
1ffe0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1fff0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
20000 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
20010 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
20020 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
20030 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
20040 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
20050 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
20060 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
20070 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
20080 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
20090 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  ack X..**.** ^On
200a0 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
200b0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
200c0 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
200d0 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
200e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
200f0 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
20100 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
20110 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
20120 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
20130 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
20140 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
20150 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
20160 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
20170 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
20180 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
20190 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
201a0 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
201b0 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
201c0 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
201d0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
201e0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
201f0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
20200 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
20210 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
20220 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
20230 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
20240 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
20250 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
20260 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
20270 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
20280 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
20290 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
202a0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
202b0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
202c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
202d0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
202e0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
202f0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
20300 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20310 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
20320 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
20330 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
20340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20350 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
20360 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
20370 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
20380 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f  h..**.*/.SQLITE_
20390 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
203a0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
203b0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
203c0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
203d0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
203e0 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
203f0 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
20400 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
20410 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
20420 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
20430 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68  database file wh
20440 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65  ose name is give
20450 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65  n by the.** file
20460 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
20470 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
20480 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
20490 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
204a0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
204b0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
204c0 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
204d0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
204e0 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
204f0 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
20500 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
20510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20520 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
20530 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
20540 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
20550 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
20560 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
20570 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
20580 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
20590 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
205a0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
205b0 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
205c0 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
205d0 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
205e0 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
205f0 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
20600 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
20610 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
20620 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
20630 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
20640 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
20650 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
20660 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
20670 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
20680 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
20690 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
206a0 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
206b0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
206c0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
206d0 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
206e0 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
206f0 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
20700 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
20710 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
20720 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
20730 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
20740 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
20750 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
20760 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
20770 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
20780 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
20790 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
207a0 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
207b0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
207c0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63  3_open_v2() is c
207d0 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
207e0 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
207f0 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
20800 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
20810 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
20820 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
20830 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
20840 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
20850 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
20860 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
20870 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
20880 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
20890 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
208a0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
208b0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
208c0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
208d0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
208e0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
208f0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
20900 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
20910 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
20920 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
20930 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
20940 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
20950 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
20960 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
20970 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
20980 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
20990 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
209a0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
209b0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
209c0 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
209d0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
209e0 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
209f0 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
20a00 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
20a10 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
20a20 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
20a30 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
20a40 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
20a50 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
20a60 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  ,.** and/or [SQL
20a70 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
20a80 43 41 43 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a  CACHE] flags:)^.
20a90 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
20aa0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
20ab0 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
20ac0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
20ad0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
20ae0 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
20af0 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
20b00 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
20b10 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
20b20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
20b30 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
20b40 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
20b50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
20b60 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
20b70 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
20b80 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
20b90 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
20ba0 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
20bb0 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
20bc0 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
20bd0 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
20be0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
20bf0 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
20c00 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
20c10 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
20c20 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
20c30 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
20c40 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
20c50 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
20c60 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
20c70 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
20c80 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
20c90 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
20ca0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
20cb0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
20cc0 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
20cd0 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
20ce0 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
20cf0 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
20d00 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
20d10 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
20d20 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
20d30 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
20d40 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
20d50 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
20d60 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
20d70 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
20d80 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
20d90 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
20da0 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
20db0 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20  above or one of 
20dc0 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  the combinations
20dd0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d   shown above com
20de0 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  bined.** with th
20df0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
20e00 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
20e10 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
20e20 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
20e30 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 61  N_SHAREDCACHE] a
20e40 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
20e50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
20e60 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20   flags,.** then 
20e70 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
20e80 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
20e90 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
20ea0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
20eb0 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
20ec0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
20ed0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
20ee0 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
20ef0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
20f00 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
20f10 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
20f20 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
20f30 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
20f40 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
20f50 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
20f60 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
20f70 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
20f80 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
20f90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
20fa0 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
20fb0 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
20fc0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
20fd0 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
20fe0 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
20ff0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
21000 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
21010 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
21020 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
21030 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
21040 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
21050 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
21060 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
21070 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
21080 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
21090 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
210a0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
210b0 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
210c0 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
210d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
210e0 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
210f0 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
21100 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
21110 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
21120 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
21130 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
21140 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
21150 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
21160 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
21170 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
21180 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
21190 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
211a0 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
211b0 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
211c0 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
211d0 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
211e0 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
211f0 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
21200 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
21210 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
21220 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
21230 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
21240 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
21250 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
21260 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
21270 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
21280 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
21290 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
212a0 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
212b0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
212c0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
212d0 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
212e0 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
212f0 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
21300 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
21310 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
21320 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
21330 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
21340 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
21350 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
21360 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
21370 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
21380 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
21390 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
213a0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
213b0 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
213c0 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
213d0 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
213e0 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
213f0 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
21400 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
21410 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
21420 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21430 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
21440 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
21450 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
21460 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
21470 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
21480 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
21490 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
214a0 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
214b0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
214c0 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
214d0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
214e0 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
214f0 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
21500 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
21510 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
21520 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
21530 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
21540 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
21550 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
21560 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
21570 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
21580 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
21590 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
215a0 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
215b0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
215c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
215d0 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
215e0 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
215f0 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
21600 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
21610 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
21620 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
21630 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
21640 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
21650 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
21660 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
21670 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
21680 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
21690 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 53  _open_v2()..*/.S
216a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
216b0 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
216c0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
216d0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
216e0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
216f0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
21700 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
21710 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
21720 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53  b handle */.);.S
21730 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
21740 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
21750 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
21760 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
21770 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
21780 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
21790 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
217a0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
217b0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
217c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
217d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
217e0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
217f0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
21800 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
21810 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
21820 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
21830 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
21840 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
21850 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
21860 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
21870 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
21880 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
21890 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
218a0 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
218b0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
218c0 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
218d0 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
218e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
218f0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
21900 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
21910 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
21920 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
21930 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
21940 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
21950 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
21960 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
21970 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
21980 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
21990 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
219a0 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
219b0 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
219c0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
219d0 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
219e0 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
219f0 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
21a00 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
21a10 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
21a20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
21a30 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
21a40 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
21a50 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
21a60 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
21a70 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
21a80 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
21a90 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
21aa0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
21ab0 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
21ac0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
21ad0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
21ae0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
21af0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
21b00 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
21b10 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
21b20 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
21b30 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
21b40 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
21b50 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
21b60 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
21b70 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
21b80 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
21b90 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
21ba0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
21bb0 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
21bc0 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
21bd0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
21be0 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
21bf0 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
21c00 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
21c10 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
21c20 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
21c30 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
21c40 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
21c50 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
21c60 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ^.**.** When the
21c70 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
21c80 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
21c90 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
21ca0 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
21cb0 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
21cc0 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
21cd0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
21ce0 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
21cf0 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
21d00 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
21d10 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
21d20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
21d30 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
21d40 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
21d50 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
21d60 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
21d70 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
21d80 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
21d90 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
21da0 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
21db0 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
21dc0 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
21dd0 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
21de0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
21df0 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
21e00 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
21e10 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
21e20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
21e30 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
21e40 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
21e50 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
21e60 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
21e70 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
21e80 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
21e90 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
21ea0 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
21eb0 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
21ec0 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
21ed0 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
21ee0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
21ef0 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
21f00 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
21f10 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
21f20 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
21f30 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
21f40 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
21f50 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
21f60 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
21f70 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
21f80 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c  t be set..*/.SQL
21f90 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
21fa0 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
21fb0 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
21fc0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
21fd0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
21fe0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
21ff0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
22000 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
22010 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
22020 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
22030 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
22040 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
22050 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
22060 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
22070 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
22080 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
22090 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
220a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
220b0 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
220c0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
220d0 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
220e0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
220f0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
22100 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
22110 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
22120 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22130 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
22140 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
22150 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
22160 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
22170 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
22180 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
22190 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
221a0 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
221b0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
221c0 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
221d0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
221e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
221f0 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
22200 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
22210 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
22220 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
22230 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
22240 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
22250 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
22260 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
22270 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
22280 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
22290 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
222a0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
222b0 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
222c0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
222d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
222e0 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
222f0 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
22300 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
22310 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
22320 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
22330 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
22340 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
22350 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
22360 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
22370 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
22380 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
22390 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
223a0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
223b0 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
223c0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
223d0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
223e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
223f0 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
22400 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
22410 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
22420 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
22430 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
22440 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
22450 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
22460 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
22470 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
22480 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
22490 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
224a0 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
224b0 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
224c0 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
224d0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
224e0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
224f0 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
22500 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
22510 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
22520 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
22530 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
22540 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
22550 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
22560 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
22570 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a  at construct.)^.
22580 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65  **.** ^If the ne
22590 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
225a0 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
225b0 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
225c0 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65  nged..** ^(For e
225d0 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ach limit catego
225e0 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ry SQLITE_LIMIT_
225f0 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72  <i>NAME</i> ther
22600 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69  e is a .** [limi
22610 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20  ts | hard upper 
22620 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74  bound].** set at
22630 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79   compile-time by
22640 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f   a C preprocesso
22650 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a  r macro called.*
22660 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49  * [limits | SQLI
22670 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f  TE_MAX_<i>NAME</
22680 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  i>]..** (The "_L
22690 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
226a0 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
226b0 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20   "_MAX_".))^.** 
226c0 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63  ^Attempts to inc
226d0 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
226e0 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
226f0 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
22700 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
22710 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
22720 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a  pper bound..**.*
22730 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66  * ^Regardless of
22740 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
22750 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68  the limit was ch
22760 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b  anged, the .** [
22770 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
22780 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
22790 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ns the prior val
227a0 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e  ue of the limit.
227b0 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66  .** ^Hence, to f
227c0 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  ind the current 
227d0 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74  value of a limit
227e0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e   without changin
227f0 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20  g it,.** simply 
22800 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65  invoke this inte
22810 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74  rface with the t
22820 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73  hird parameter s
22830 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20  et to -1..**.** 
22840 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
22850 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
22860 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
22870 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
22880 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
22890 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
228a0 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
228b0 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
228c0 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
228d0 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
228e0 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
228f0 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
22900 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
22910 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
22920 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
22930 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
22940 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
22950 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
22960 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
22970 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
22980 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
22990 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
229a0 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
229b0 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
229c0 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
229d0 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
229e0 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
229f0 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
22a00 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
22a10 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
22a20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
22a30 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
22a40 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
22a50 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
22a60 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
22a70 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
22a80 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
22a90 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
22aa0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
22ab0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
22ac0 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
22ad0 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
22ae0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
22af0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
22b00 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
22b10 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
22b20 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
22b30 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
22b40 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
22b50 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
22b60 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
22b70 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
22b80 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
22b90 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51   releases..*/.SQ
22ba0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
22bb0 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
22bc0 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
22bd0 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
22be0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
22bf0 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
22c00 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
22c10 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
22c20 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
22c30 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
22c40 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
22c50 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
22c60 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
22c70 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
22c80 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
22c90 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
22ca0 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
22cb0 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
22cc0 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
22cd0 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
22ce0 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
22cf0 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
22d00 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
22d10 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
22d20 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
22d30 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
22d40 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  l>.** ^(<dt>SQLI
22d50 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
22d60 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
22d70 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
22d80 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
22d90 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
22da0 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
22db0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
22dc0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
22dd0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
22de0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
22df0 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
22e00 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
22e10 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
22e20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
22e30 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
22e40 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
22e50 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
22e60 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
22e70 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
22e80 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
22e90 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
22ea0 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
22eb0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
22ec0 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
22ed0 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
22ee0 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
22ef0 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
22f00 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
22f10 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
22f20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
22f30 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
22f40 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
22f50 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
22f60 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
22f70 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
22f80 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
22f90 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
22fa0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
22fb0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
22fc0 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
22fd0 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
22fe0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
22ff0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
23000 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
23010 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
23020 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
23030 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
23040 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
23050 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
23060 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
23070 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
23080 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
23090 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
230a0 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
230b0 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
230c0 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
230d0 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
230e0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
230f0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
23100 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
23110 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
23120 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
23130 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
23140 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
23150 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
23160 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
23170 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
23180 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
23190 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
231a0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
231b0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
231c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
231d0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
231e0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
231f0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
23200 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
23210 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
23220 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
23230 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
23240 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
23250 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
23260 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
23270 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
23280 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
23290 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
232a0 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
232b0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
232c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
232d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
232e0 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
232f0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
23300 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
23310 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
23320 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
23330 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
23340 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
23350 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
23360 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
23370 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
23380 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
23390 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
233a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
233b0 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
233c0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
233d0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
233e0 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
233f0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
23400 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
23410 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
23420 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
23430 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
23440 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
23450 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
23460 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
23470 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
23480 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
23490 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
234a0 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
234b0 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
234c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
234d0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
234e0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
234f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
23500 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
23510 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
23520 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
23530 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
23540 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
23550 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23560 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
23570 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
23580 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
23590 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
235a0 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
235b0 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
235c0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
235d0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
235e0 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
235f0 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
23600 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
23610 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
23620 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
23630 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
23640 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
23650 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
23660 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
23670 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
23680 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
23690 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
236a0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
236b0 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
236c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
236d0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
236e0 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
236f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
23700 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
23710 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
23720 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
23730 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
23740 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
23750 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
23760 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
23770 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
23780 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
23790 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
237a0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
237b0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
237c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
237d0 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
237e0 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
237f0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
23800 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
23810 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
23820 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
23830 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
23840 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
23850 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
23860 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
23870 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
23880 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
23890 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
238a0 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
238b0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
238c0 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
238d0 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
238e0 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
238f0 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
23900 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
23910 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
23920 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
23930 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
23940 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
23950 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
23960 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
23970 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
23980 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
23990 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
239a0 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
239b0 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
239c0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
239d0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
239e0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
239f0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
23a00 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
23a10 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
23a20 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
23a30 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a  minator bytes..*
23a40 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20  *.** ^If pzTail 
23a50 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
23a60 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
23a70 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
23a80 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70   first byte.** p
23a90 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
23aa0 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
23ab0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
23ac0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
23ad0 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20  only.** compile 
23ae0 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
23af0 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
23b00 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
23b10 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77  pointing to.** w
23b20 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
23b30 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a  mpiled..**.** ^*
23b40 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
23b50 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
23b60 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
23b70 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
23b80 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
23b90 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
23ba0 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20  3_step()].  ^If 
23bb0 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
23bc0 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  r, *ppStmt is se
23bd0 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e  t.** to NULL.  ^
23be0 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78  If the input tex
23bf0 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  t contains no SQ
23c00 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
23c10 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73  is an empty.** s
23c20 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
23c30 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
23c40 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
23c50 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  .** The calling 
23c60 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
23c70 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
23c80 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
23c90 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
23ca0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
23cb0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
23cc0 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
23cd0 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
23ce0 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20   ppStmt may not 
23cf0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
23d00 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20  On success, the 
23d10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
23d20 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74  ) family of rout
23d30 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
23d40 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65  ITE_OK];.** othe
23d50 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
23d60 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
23d70 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
23d80 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
23d90 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
23da0 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
23db0 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
23dc0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
23dd0 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
23de0 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
23df0 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
23e00 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
23e10 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
23e20 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
23e30 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
23e40 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ged..** ^In the 
23e50 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "v2" interfaces,
23e60 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
23e70 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
23e80 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
23e90 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
23ea0 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
23eb0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
23ec0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
23ed0 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
23ee0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
23ef0 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
23f00 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66  to.** behave dif
23f10 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65  ferently in thre
23f20 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e ways:.**.** <o
23f30 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  l>.** <li>.** ^I
23f40 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
23f50 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
23f60 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
23f70 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
23f80 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
23f90 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
23fa0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23fb0 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
23fc0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
23fd0 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
23fe0 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
23ff0 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c  n it again..** <
24000 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
24010 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
24020 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
24030 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
24040 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
24050 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
24060 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
24070 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
24080 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
24090 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
240a0 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
240b0 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
240c0 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
240d0 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
240e0 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
240f0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c  .** and the appl
24100 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61  ication would ha
24110 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
24120 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
24130 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
24140 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
24150 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
24160 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
24170 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
24180 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
24190 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
241a0 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
241b0 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
241c0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
241d0 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
241e0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
241f0 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63  ^If the specific
24200 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20   value bound to 
24210 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73  [parameter | hos
24220 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  t parameter] in 
24230 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c  the .** WHERE cl
24240 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75  ause might influ
24250 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20  ence the choice 
24260 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f  of query plan fo
24270 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a  r a statement,.*
24280 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  * then the state
24290 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74  ment will be aut
242a0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
242b0 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65  piled, as if the
242c0 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20  re had been .** 
242d0 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c  a schema change,
242e0 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b   on the first  [
242f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
24300 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  call following a
24310 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20  ny change.** to 
24320 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
24330 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67  d_text | binding
24340 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61  s] of that [para
24350 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65  meter]. .** ^The
24360 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
24370 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20  of WHERE-clause 
24380 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68  [parameter] migh
24390 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
243a0 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75  .** choice of qu
243b0 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20  ery plan if the 
243c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
243d0 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
243e0 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f  of a [LIKE].** o
243f0 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  r [GLOB] operato
24400 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61  r or if the para
24410 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65  meter is compare
24420 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20  d to an indexed 
24430 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68  column.** and th
24440 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
24450 5f 53 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65 2d  _STAT2] compile-
24460 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
24470 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a  nabled..** the .
24480 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
24490 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  >.*/.SQLITE_API 
244a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
244b0 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
244c0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
244d0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
244e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
244f0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
24500 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
24510 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
24520 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
24530 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
24540 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
24550 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
24560 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
24570 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
24580 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
24590 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
245a0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
245b0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
245c0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
245d0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
245e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
245f0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
24600 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
24610 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
24620 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
24630 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
24640 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
24650 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
24660 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
24670 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
24680 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
24690 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
246a0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
246b0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
246c0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
246d0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
246e0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
246f0 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
24700 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
24710 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
24720 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
24730 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
24740 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
24750 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
24760 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
24770 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
24780 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
24790 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
247a0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
247b0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
247c0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
247d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
247e0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
247f0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
24800 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
24810 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
24820 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
24830 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
24840 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
24850 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
24860 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
24870 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
24880 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
24890 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
248a0 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69  are16_v2(.  sqli
248b0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
248c0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
248d0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
248e0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
248f0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
24900 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
24910 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
24920 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
24930 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
24940 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
24950 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
24960 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
24970 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
24980 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
24990 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
249a0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
249b0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
249c0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
249d0 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
249e0 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
249f0 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53  ving Statement S
24a00 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  QL.**.** ^This i
24a10 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
24a20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
24a30 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
24a40 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
24a50 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
24a60 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
24a70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24a80 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  if that statemen
24a90 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  t was.** compile
24aa0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
24ab0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
24ac0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
24ad0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
24ae0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
24af0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
24b00 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
24b10 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
24b20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24b30 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
24b40 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
24b50 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
24b60 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
24b70 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
24b80 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
24b90 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
24ba0 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
24bb0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
24bc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24bd0 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
24be0 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
24bf0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
24c00 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
24c10 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
24c20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
24c30 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
24c40 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
24c50 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
24c60 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
24c70 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
24c80 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
24c90 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
24ca0 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
24cb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
24cc0 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
24cd0 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
24ce0 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
24cf0 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
24d00 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
24d10 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
24d20 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
24d30 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
24d40 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
24d50 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
24d60 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
24d70 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
24d80 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
24d90 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
24da0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
24db0 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
24dc0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
24dd0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
24de0 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
24df0 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
24e00 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
24e10 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
24e20 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
24e30 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
24e40 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
24e50 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
24e60 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
24e70 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
24e80 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
24e90 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
24ea0 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
24eb0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
24ec0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
24ed0 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
24ee0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
24ef0 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
24f00 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
24f10 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
24f20 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
24f30 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
24f40 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
24f50 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
24f60 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
24f70 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
24f80 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
24f90 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
24fa0 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
24fb0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
24fc0 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
24fd0 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
24fe0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
24ff0 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
25000 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
25010 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25020 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
25030 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
25040 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
25050 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
25060 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
25070 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
25080 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
25090 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
250a0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
250b0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
250c0 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
250d0 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
250e0 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
250f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
25100 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
25110 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
25120 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
25130 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
25140 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
25150 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
25160 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
25170 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
25180 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
25190 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
251a0 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
251b0 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
251c0 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
251d0 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
251e0 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
251f0 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
25200 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
25210 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
25220 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
25230 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
25240 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
25250 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
25260 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
25270 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
25280 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
25290 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
252a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
252b0 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
252c0 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
252d0 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
252e0 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
252f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
25300 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
25310 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
25320 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
25330 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
25340 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
25350 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
25360 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
25370 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
25380 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
25390 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
253a0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
253b0 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
253c0 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
253d0 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
253e0 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
253f0 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
25400 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
25410 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
25420 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
25430 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
25440 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
25450 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
25460 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
25470 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
25480 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
25490 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
254a0 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
254b0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
254c0 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
254d0 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
254e0 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
254f0 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
25500 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
25510 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
25520 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
25530 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
25540 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
25550 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
25560 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
25570 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
25580 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
25590 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
255a0 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
255b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
255c0 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
255d0 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
255e0 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
255f0 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
25600 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
25610 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
25620 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
25630 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
25640 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
25650 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
25660 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
25670 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
25680 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
25690 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
256a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
256b0 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
256c0 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
256d0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
256e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
256f0 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
25700 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
25710 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
25720 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
25730 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
25740 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
25750 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
25760 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
25770 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
25780 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
25790 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
257a0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
257b0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
257c0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
257d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
257e0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
257f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
25800 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
25810 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
25820 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
25830 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
25840 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
25850 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
25860 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
25870 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
25880 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
25890 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
258a0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
258b0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
258c0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
258d0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
258e0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
258f0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
25900 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
25910 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
25920 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
25930 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
25940 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
25950 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
25960 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25970 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
25980 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
25990 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
259a0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
259b0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
259c0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
259d0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
259e0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
259f0 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
25a00 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
25a10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
25a20 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
25a30 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
25a40 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
25a50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
25a60 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
25a70 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
25a80 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
25a90 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
25aa0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
25ab0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
25ac0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
25ad0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
25ae0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
25af0 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
25b00 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
25b10 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
25b20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
25b30 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
25b40 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
25b50 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
25b60 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
25b70 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
25b80 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
25b90 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
25ba0 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
25bb0 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
25bc0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
25bd0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
25be0 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
25bf0 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
25c00 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
25c10 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
25c20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
25c30 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
25c40 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
25c50 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
25c60 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
25c70 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
25c80 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
25c90 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
25ca0 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
25cb0 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
25cc0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
25cd0 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
25ce0 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
25cf0 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
25d00 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
25d10 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
25d20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
25d30 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
25d40 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
25d50 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
25d60 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
25d70 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
25d80 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
25d90 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
25da0 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
25db0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
25dc0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
25dd0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
25de0 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
25df0 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
25e00 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
25e10 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
25e20 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
25e30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25e40 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
25e50 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
25e60 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
25e70 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
25e80 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
25e90 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
25ea0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
25eb0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
25ec0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
25ed0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
25ee0 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
25ef0 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
25f00 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
25f10 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
25f20 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
25f30 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
25f40 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
25f50 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
25f60 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
25f70 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
25f80 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
25f90 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
25fa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
25fb0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
25fc0 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
25fd0 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
25fe0 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
25ff0 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
26000 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
26010 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
26020 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
26030 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
26040 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
26050 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
26060 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
26070 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
26080 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
26090 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
260a0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
260b0 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
260c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
260d0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
260e0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
260f0 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
26100 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
26110 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
26120 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
26130 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
26140 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
26150 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
26160 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
26170 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
26180 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
26190 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
261a0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
261b0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
261c0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
261d0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
261e0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
261f0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
26200 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
26210 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
26220 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
26230 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
26240 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
26250 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
26260 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
26270 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
26280 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
26290 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
262a0 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
262b0 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
262c0 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
262d0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
262e0 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
262f0 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  r is called.** t
26300 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
26310 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
26320 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  even if the call
26330 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
26340 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69  _blob(),.** sqli
26350 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
26360 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
26370 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e  _text16() fails.
26380 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69    .** ^If the fi
26390 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
263a0 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
263b0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
263c0 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
263d0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
263e0 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
263f0 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
26400 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
26410 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
26420 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
26430 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
26440 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
26450 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
26460 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
26470 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
26480 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
26490 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
264a0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
264b0 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
264c0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
264d0 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
264e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
264f0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
26500 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
26510 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
26520 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
26530 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
26540 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
26550 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
26560 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
26570 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
26580 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
26590 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
265a0 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
265b0 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
265c0 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
265d0 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
265e0 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
265f0 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
26600 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
26610 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
26620 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
26630 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
26640 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
26650 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
26660 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
26670 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
26680 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
26690 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
266a0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
266b0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
266c0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
266d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
266e0 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
266f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
26700 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
26710 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
26720 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
26730 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
26740 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
26750 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
26760 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
26770 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
26780 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
26790 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
267a0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
267b0 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
267c0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
267d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
267e0 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
267f0 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
26800 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
26810 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
26820 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
26830 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
26840 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
26850 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
26860 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
26870 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
26880 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
26890 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
268a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
268b0 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
268c0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
268d0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
268e0 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
268f0 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
26900 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
26910 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
26920 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
26930 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
26940 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
26950 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
26960 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
26970 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
26980 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
26990 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
269a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
269b0 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
269c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
269d0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
269e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
269f0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
26a00 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
26a10 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
26a20 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
26a30 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
26a40 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
26a50 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
26a60 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
26a70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
26a80 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
26a90 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
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 69 6e 74 28  qlite3_bind_int(
26ac0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
26ad0 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  nt, int);.SQLITE
26ae0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
26af0 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
26b00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
26b10 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
26b20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
26b30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
26b40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26b50 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
26b60 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
26b70 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
26b80 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
26b90 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
26ba0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
26bb0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
26bc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
26bd0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
26be0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
26bf0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
26c00 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
26c10 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
26c20 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
26c30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
26c40 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
26c50 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
26c60 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
26c70 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
26c80 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
26c90 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
26ca0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
26cb0 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
26cc0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
26cd0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
26ce0 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
26cf0 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
26d00 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
26d10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26d20 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
26d30 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
26d40 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
26d50 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
26d60 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
26d70 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
26d80 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
26d90 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
26da0 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
26db0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
26dc0 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
26dd0 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
26de0 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
26df0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
26e00 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
26e10 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
26e20 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
26e30 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
26e40 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
26e50 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
26e60 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
26e70 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
26e80 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
26e90 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
26ea0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
26eb0 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
26ec0 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
26ed0 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
26ee0 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
26ef0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
26f00 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
26f10 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
26f20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26f30 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
26f40 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
26f50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
26f60 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
26f70 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
26f80 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
26f90 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
26fa0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
26fb0 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
26fc0 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
26fd0 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ter.**.** ^The s
26fe0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
26ff0 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
27000 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27010 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
27020 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
27030 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
27040 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27050 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
27060 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
27070 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
27080 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
27090 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
270a0 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
270b0 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
270c0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
270d0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
270e0 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
270f0 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
27100 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
27110 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
27120 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
27130 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
27140 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
27150 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
27160 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
27170 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
27180 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
27190 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
271a0 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
271b0 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
271c0 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
271d0 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
271e0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
271f0 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
27200 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
27210 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
27220 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
27230 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
27240 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
27250 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
27260 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
27270 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
27280 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
27290 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
272a0 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
272b0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
272c0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
272d0 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
272e0 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
272f0 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
27300 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
27310 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
27320 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
27330 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
27340 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
27350 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
27360 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
27370 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
27380 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
27390 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
273a0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
273b0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
273c0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
273d0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
273e0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
273f0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
27400 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
27410 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
27420 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
27430 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  e.**.** ^Return 
27440 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
27450 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
27460 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
27470 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
27480 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
27490 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
274a0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
274b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
274c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
274d0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
274e0 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
274f0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
27500 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
27510 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
27520 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
27530 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
27540 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
27550 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
27560 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
27570 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
27580 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
27590 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
275a0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
275b0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
275c0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
275d0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
275e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
275f0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
27600 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
27610 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
27620 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
27630 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
27640 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
27650 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
27660 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
27670 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
27680 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27690 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
276a0 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
276b0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
276c0 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
276d0 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
276e0 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
276f0 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
27700 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
27710 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
27720 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
27730 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
27740 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
27750 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
27760 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
27770 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
27780 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  L..*/.SQLITE_API
27790 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65   int sqlite3_cle
277a0 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
277b0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
277c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
277d0 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
277e0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
277f0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
27800 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
27810 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
27820 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
27830 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
27840 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
27850 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
27860 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
27870 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
27880 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
27890 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
278a0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
278b0 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
278c0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
278d0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
278e0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
278f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
27900 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
27910 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
27920 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27930 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
27940 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
27950 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
27960 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
27970 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
27980 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
27990 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
279a0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
279b0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
279c0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
279d0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
279e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
279f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
27a00 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
27a10 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
27a20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
27a30 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
27a40 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
27a50 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
27a60 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
27a70 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
27a80 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
27a90 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
27aa0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
27ab0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
27ac0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
27ad0 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
27ae0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
27af0 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
27b00 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
27b10 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
27b20 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
27b30 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
27b40 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
27b50 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
27b60 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27b70 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
27b80 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
27b90 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
27ba0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
27bb0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
27bc0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
27bd0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
27be0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
27bf0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
27c00 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
27c10 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
27c20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
27c30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
27c40 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
27c50 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
27c60 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
27c70 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
27c80 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
27c90 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
27ca0 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
27cb0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
27cc0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
27cd0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
27ce0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
27cf0 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
27d00 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
27d10 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
27d20 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
27d30 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
27d40 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
27d50 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
27d60 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
27d70 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
27d80 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
27d90 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
27da0 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
27db0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
27dc0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
27dd0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
27de0 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
27df0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
27e00 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
27e10 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
27e20 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
27e30 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
27e40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
27e50 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  N);.SQLITE_API c
27e60 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
27e70 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
27e80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27e90 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
27ea0 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
27eb0 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
27ec0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
27ed0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
27ee0 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
27ef0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
27f00 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
27f10 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
27f20 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
27f30 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
27f40 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
27f50 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
27f60 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
27f70 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
27f80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
27f90 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
27fa0 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
27fb0 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
27fc0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
27fd0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
27fe0 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
27ff0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
28000 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
28010 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
28020 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
28030 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
28040 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
28050 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
28060 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
28070 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
28080 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
28090 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
280a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
280b0 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
280c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
280d0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
280e0 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
280f0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
28100 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
28110 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
28120 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
28130 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
28140 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
28150 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
28160 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
28170 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
28180 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
28190 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
281a0 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75   ^The names retu
281b0 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
281c0 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
281d0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
281e0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
281f0 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
28200 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
28210 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65  rgument to these
28220 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61   interfaces is a
28230 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28240 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65  ment]..** ^These
28250 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
28260 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
28270 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75  out the Nth resu
28280 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  lt column return
28290 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
282a0 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
282b0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
282c0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
282d0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f  .** ^The left-mo
282e0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c  st column is col
282f0 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20  umn 0 for these 
28300 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
28310 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
28320 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
28330 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
28340 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
28350 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
28360 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
28370 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
28380 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
28390 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
283a0 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  LL.  ^These rout
283b0 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  ine might also r
283c0 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20  eturn NULL if a 
283d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
283e0 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72  n error.** occur
283f0 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20  s.  ^Otherwise, 
28400 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
28410 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
28420 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
28430 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75  able,.** or colu
28440 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
28450 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
28460 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
28470 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61  **.** ^As with a
28480 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
28490 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73  APIs, those whos
284a0 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68  e names end with
284b0 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
284c0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
284d0 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f  trings and the o
284e0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
284f0 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
28500 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61  ** ^These APIs a
28510 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
28520 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
28530 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
28540 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
28550 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
28560 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
28570 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e  rocessor symbol.
28580 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
28590 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
285a0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
285b0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
285c0 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
285d0 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
285e0 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
285f0 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
28600 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
28610 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
28620 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
28630 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
28640 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
28650 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
28660 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
28670 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
28680 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
28690 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
286a0 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
286b0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
286c0 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
286d0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
286e0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
286f0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
28700 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
28710 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
28720 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
28730 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
28740 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
28750 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
28760 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
28770 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
28780 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
28790 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
287a0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
287b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
287c0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
287d0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
287e0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
287f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28800 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
28810 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
28820 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
28830 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
28840 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
28850 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
28860 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
28870 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
28880 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
28890 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
288a0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
288b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
288c0 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
288d0 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
288e0 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  lt.**.** ^(The f
288f0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
28900 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
28910 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
28920 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
28930 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
28940 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
28950 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
28960 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
28970 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
28980 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
28990 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
289a0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
289b0 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
289c0 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
289d0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
289e0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
289f0 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
28a00 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
28a10 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
28a20 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
28a30 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
28a40 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
28a50 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
28a60 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
28a70 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
28a80 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
28a90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
28aa0 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
28ab0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
28ac0 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
28ad0 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
28ae0 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
28af0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
28b00 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
28b10 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
28b20 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
28b30 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
28b40 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
28b50 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
28b60 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
28b70 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
28b80 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
28b90 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
28ba0 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
28bb0 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
28bc0 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
28bd0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
28be0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
28bf0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
28c00 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
28c10 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
28c20 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
28c30 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
28c40 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
28c50 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
28c60 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
28c70 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
28c80 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
28c90 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
28ca0 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
28cb0 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
28cc0 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
28cd0 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
28ce0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
28cf0 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
28d00 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
28d10 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
28d20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
28d30 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51  se values..*/.SQ
28d40 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
28d50 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
28d60 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
28d70 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
28d80 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
28d90 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
28da0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
28db0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
28dc0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
28dd0 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
28de0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
28df0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
28e00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28e10 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
28e20 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
28e30 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
28e40 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
28e50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28e60 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
28e70 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
28e80 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
28e90 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
28ea0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
28eb0 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
28ec0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
28ed0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
28ee0 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
28ef0 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
28f00 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
28f10 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
28f20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
28f30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
28f40 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
28f50 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
28f60 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
28f70 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
28f80 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
28f90 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
28fa0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
28fb0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
28fc0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
28fd0 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
28fe0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
28ff0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29000 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
29010 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
29020 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
29030 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
29040 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
29050 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
29060 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
29070 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
29080 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
29090 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
290a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
290b0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
290c0 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
290d0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
290e0 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
290f0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
29100 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
29110 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
29120 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
29130 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
29140 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
29150 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
29160 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
29170 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
29180 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
29190 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
291a0 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
291b0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
291c0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
291d0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
291e0 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
291f0 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
29200 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
29210 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
29220 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
29230 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
29240 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
29250 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
29260 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
29270 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
29280 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
29290 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
292a0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
292b0 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
292c0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
292d0 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
292e0 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
292f0 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
29300 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
29310 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
29320 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
29330 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
29340 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
29350 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
29360 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
29370 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
29380 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
29390 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
293a0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
293b0 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
293c0 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
293d0 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
293e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
293f0 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
29400 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
29410 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
29420 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
29430 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
29440 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
29450 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
29460 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
29470 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
29480 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
29490 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
294a0 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
294b0 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
294c0 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
294d0 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
294e0 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
294f0 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
29500 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
29510 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
29520 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
29530 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
29540 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
29550 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
29560 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
29570 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
29580 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
29590 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
295a0 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
295b0 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
295c0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
295d0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
295e0 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
295f0 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
29600 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
29610 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
29620 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
29630 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
29640 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
29650 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
29660 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
29670 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
29680 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
29690 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
296a0 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
296b0 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
296c0 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
296d0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
296e0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
296f0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
29700 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
29710 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
29720 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
29730 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
29740 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
29750 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
29760 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
29770 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
29780 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
29790 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
297a0 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
297b0 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
297c0 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
297d0 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
297e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
297f0 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
29800 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
29810 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
29820 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
29830 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
29840 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
29850 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
29860 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
29870 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
29880 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
29890 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
298a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
298b0 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
298c0 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
298d0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
298e0 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
298f0 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
29900 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
29910 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
29920 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
29930 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
29940 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29950 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
29960 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
29970 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
29980 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
29990 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
299a0 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
299b0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
299c0 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
299d0 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
299e0 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
299f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29a00 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
29a10 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
29a20 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
29a30 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
29a40 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
29a50 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
29a60 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
29a70 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
29a80 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
29a90 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
29aa0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
29ab0 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
29ac0 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
29ad0 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
29ae0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
29af0 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
29b00 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
29b10 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
29b20 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
29b30 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
29b40 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
29b50 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
29b60 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
29b70 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
29b80 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
29b90 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
29ba0 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
29bb0 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
29bc0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
29bd0 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
29be0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
29bf0 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
29c00 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
29c10 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
29c20 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
29c30 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
29c40 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
29c50 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
29c60 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
29c70 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
29c80 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
29c90 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
29ca0 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
29cb0 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
29cc0 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
29cd0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
29ce0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
29cf0 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
29d00 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
29d10 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
29d20 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
29d30 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
29d40 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
29d50 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
29d60 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
29d70 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
29d80 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
29d90 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
29da0 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
29db0 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
29dc0 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
29dd0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
29de0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
29df0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
29e00 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
29e10 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
29e20 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
29e30 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
29e40 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
29e50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
29e60 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
29e70 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
29e80 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
29e90 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
29ea0 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
29eb0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
29ec0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
29ed0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
29ee0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
29ef0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
29f00 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
29f10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
29f20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29f30 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
29f40 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
29f50 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
29f60 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
29f70 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
29f80 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
29f90 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
29fa0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
29fb0 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
29fc0 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
29fd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
29fe0 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
29ff0 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
2a000 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
2a010 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
2a020 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
2a030 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2a040 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
2a050 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
2a060 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
2a070 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
2a080 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
2a090 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
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 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
2a0c0 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
2a0d0 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
2a0e0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  nter..**.** See 
2a0f0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
2a100 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
2a110 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2a120 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2a130 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2a140 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2a150 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
2a160 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
2a170 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
2a180 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
2a190 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
2a1a0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
2a1b0 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
2a1c0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
2a1d0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2a1e0 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
2a1f0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
2a200 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
2a210 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2a220 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
2a230 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
2a240 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
2a250 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
2a260 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
2a270 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
2a280 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
2a290 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
2a2a0 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
2a2b0 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
2a2c0 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
2a2d0 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
2a2e0 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
2a2f0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
2a300 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
2a310 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
2a320 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
2a330 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
2a340 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
2a350 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
2a360 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
2a370 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
2a380 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
2a390 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
2a3a0 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
2a3b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
2a3c0 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
2a3d0 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
2a3e0 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
2a3f0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
2a400 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
2a410 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2a420 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
2a430 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
2a440 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
2a450 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2a460 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
2a470 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
2a480 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
2a490 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
2a4a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2a4b0 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
2a4c0 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
2a4d0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
2a4e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2a4f0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2a500 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
2a510 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
2a520 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
2a530 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
2a540 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
2a550 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2a560 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
2a570 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
2a580 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2a590 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
2a5a0 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
2a5b0 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
2a5c0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
2a5d0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
2a5e0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
2a5f0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
2a600 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
2a610 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2a620 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2a630 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
2a640 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
2a650 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
2a660 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
2a670 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
2a680 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
2a690 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
2a6a0 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
2a6b0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2a6c0 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
2a6d0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
2a6e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2a6f0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
2a700 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
2a710 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2a720 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
2a730 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
2a740 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
2a750 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
2a760 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
2a770 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
2a780 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
2a790 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
2a7a0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
2a7b0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2a7c0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2a7d0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2a7e0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2a7f0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
2a800 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2a810 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
2a820 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
2a830 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
2a840 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
2a850 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
2a860 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2a870 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
2a880 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2a890 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2a8a0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
2a8b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2a8c0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
2a8d0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
2a8e0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2a8f0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
2a900 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2a910 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
2a920 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2a930 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2a940 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2a950 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
2a960 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
2a970 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
2a980 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2a990 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
2a9a0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
2a9b0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2a9c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2a9d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a9e0 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
2a9f0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
2aa00 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2aa10 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
2aa20 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
2aa30 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
2aa40 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
2aa50 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2aa60 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
2aa70 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
2aa80 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
2aa90 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
2aaa0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
2aab0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
2aac0 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
2aad0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2aae0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2aaf0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
2ab00 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
2ab10 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
2ab20 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
2ab30 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
2ab40 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
2ab50 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
2ab60 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
2ab70 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2ab80 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2ab90 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
2aba0 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
2abb0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
2abc0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
2abd0 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
2abe0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
2abf0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
2ac00 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
2ac10 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2ac20 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2ac30 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
2ac40 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2ac50 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
2ac60 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2ac70 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2ac80 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2ac90 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2aca0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2acb0 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
2acc0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2acd0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
2ace0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2acf0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
2ad00 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2ad10 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2ad20 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2ad30 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2ad40 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2ad50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2ad60 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2ad70 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2ad80 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2ad90 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
2ada0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2adb0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2adc0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2add0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2ade0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2adf0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2ae00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2ae10 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2ae20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2ae30 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2ae40 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
2ae50 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2ae60 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
2ae70 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2ae80 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2ae90 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2aea0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2aeb0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2aec0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
2aed0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2aee0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2aef0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2af00 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2af10 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
2af20 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2af30 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2af40 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2af50 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2af60 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2af70 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
2af80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2af90 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2afa0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2afb0 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
2afc0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2afd0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2afe0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2aff0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2b000 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2b010 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2b020 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
2b030 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2b040 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
2b050 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2b060 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2b070 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
2b080 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2b090 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
2b0a0 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
2b0b0 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
2b0c0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
2b0d0 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
2b0e0 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
2b0f0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2b100 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2b110 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
2b120 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2b130 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
2b140 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
2b150 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
2b160 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2b170 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
2b180 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
2b190 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2b1a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2b1b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2b1c0 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
2b1d0 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
2b1e0 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
2b1f0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e  zero terminated.
2b200 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
2b210 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
2b220 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2b230 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
2b240 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
2b250 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
2b260 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  * ^The object re
2b270 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2b280 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2b290 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
2b2a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2b2b0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
2b2c0 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
2b2d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2b2e0 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
2b2f0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
2b300 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2b310 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2b320 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2b330 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
2b340 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b350 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2b360 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2b370 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2b380 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
2b390 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
2b3a0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
2b3b0 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
2b3c0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
2b3d0 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
2b3e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2b3f0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
2b400 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2b410 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
2b420 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2b430 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
2b440 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
2b450 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
2b460 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
2b470 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
2b480 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
2b490 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
2b4a0 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
2b4b0 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
2b4c0 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
2b4d0 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
2b4e0 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
2b4f0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
2b500 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
2b510 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
2b520 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
2b530 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
2b540 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
2b550 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
2b560 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
2b570 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2b580 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
2b590 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
2b5a0 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
2b5b0 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
2b5c0 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
2b5d0 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
2b5e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2b5f0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2b600 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2b610 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
2b620 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
2b630 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
2b640 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
2b650 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2b660 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2b670 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
2b680 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
2b690 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2b6a0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2b6b0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
2b6c0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
2b6d0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2b6e0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2b6f0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2b700 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
2b710 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
2b720 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
2b730 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2b740 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2b750 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
2b760 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2b770 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2b780 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
2b790 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
2b7a0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2b7b0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2b7c0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66  > Convert from f
2b7d0 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a  loat to integer.
2b7e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2b7f0 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
2b800 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
2b810 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
2b820 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2b830 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2b840 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
2b850 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45  ame as FLOAT->TE
2b860 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
2b870 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
2b880 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20  EGER   <td> Use 
2b890 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
2b8a0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2b8b0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2b8c0 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  Use atof().** <t
2b8d0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2b8e0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2b8f0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
2b900 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2b910 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2b920 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
2b930 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
2b940 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
2b950 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2b960 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2b970 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
2b980 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a  then use atof().
2b990 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2b9a0 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
2b9b0 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
2b9c0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
2b9d0 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
2b9e0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
2b9f0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  uote>)^.**.** Th
2ba00 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61  e table above ma
2ba10 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f  kes reference to
2ba20 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
2ba30 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74  ary functions at
2ba40 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66  oi().** and atof
2ba50 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73  ().  SQLite does
2ba60 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20   not really use 
2ba70 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
2ba80 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20    It has its.** 
2ba90 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69  own equivalent i
2baa0 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
2bab0 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
2bac0 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
2bad0 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
2bae0 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
2baf0 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
2bb00 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
2bb10 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
2bb20 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
2bb30 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
2bb40 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2bb50 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
2bb60 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
2bb70 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
2bb80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2bb90 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
2bba0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
2bbb0 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
2bbc0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2bbd0 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
2bbe0 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
2bbf0 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
2bc00 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
2bc10 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
2bc20 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
2bc30 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
2bc40 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
2bc50 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2bc60 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
2bc70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2bc80 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
2bc90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2bca0 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
2bcb0 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
2bcc0 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
2bcd0 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
2bce0 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
2bcf0 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
2bd00 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2bd10 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
2bd20 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
2bd30 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
2bd40 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2bd50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2bd60 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2bd70 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2bd80 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2bd90 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
2bda0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2bdb0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2bdc0 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
2bdd0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2bde0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2bdf0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2be00 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
2be10 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
2be20 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
2be30 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
2be40 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
2be50 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
2be60 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
2be70 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
2be80 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
2be90 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
2bea0 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
2beb0 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
2bec0 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
2bed0 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
2bee0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
2bef0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
2bf00 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
2bf10 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
2bf20 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
2bf30 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
2bf40 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
2bf50 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
2bf60 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
2bf70 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
2bf80 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
2bf90 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
2bfa0 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
2bfb0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
2bfc0 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
2bfd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
2bfe0 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
2bff0 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
2c000 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
2c010 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2c020 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
2c030 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
2c040 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
2c050 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2c060 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
2c070 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2c080 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2c090 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2c0a0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
2c0b0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2c0c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
2c0d0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
2c0e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c0f0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
2c100 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c110 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
2c120 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
2c130 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
2c140 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
2c150 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c160 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
2c170 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
2c180 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2c190 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
2c1a0 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
2c1b0 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
2c1c0 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
2c1d0 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
2c1e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c1f0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2c200 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c210 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
2c220 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
2c230 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
2c240 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
2c250 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2c260 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2c270 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
2c280 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2c290 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2c2a0 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
2c2b0 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
2c2c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2c2d0 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
2c2e0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2c2f0 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
2c300 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
2c310 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
2c320 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
2c330 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
2c340 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
2c350 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
2c360 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
2c370 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2c380 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2c390 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2c3a0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
2c3b0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
2c3c0 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
2c3d0 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
2c3e0 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
2c3f0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
2c400 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
2c410 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
2c420 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  urned.** [sqlite
2c430 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
2c440 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
2c450 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
2c460 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
2c470 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
2c480 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
2c490 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
2c4a0 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
2c4b0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
2c4c0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
2c4d0 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
2c4e0 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
2c4f0 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
2c500 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
2c510 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
2c520 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
2c530 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
2c540 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
2c550 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
2c560 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
2c570 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2c580 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
2c590 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
2c5a0 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
2c5b0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2c5c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2c5d0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2c5e0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2c5f0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2c600 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2c610 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c620 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2c630 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2c640 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c650 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c660 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2c670 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69  _API double sqli
2c680 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
2c690 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2c6a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2c6b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2c6c0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
2c6d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c6e0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2c6f0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
2c700 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c710 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2c720 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2c730 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2c740 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2c750 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c760 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2c770 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2c780 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2c790 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2c7a0 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
2c7b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2c7c0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2c7d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2c7e0 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
2c7f0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2c800 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
2c810 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
2c820 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2c830 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c840 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
2c850 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
2c860 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
2c870 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
2c880 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c890 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
2c8a0 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
2c8b0 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
2c8c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c8d0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
2c8e0 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
2c8f0 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
2c900 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
2c910 64 20 6e 6f 20 65 72 72 6f 72 73 20 6f 72 0a 2a  d no errors or.*
2c920 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
2c930 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
2c940 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
2c950 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
2c960 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
2c970 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
2c980 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2c990 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2c9a0 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
2c9b0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
2c9c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
2c9d0 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
2c9e0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2c9f0 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
2ca00 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
2ca10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2ca20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2ca30 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2ca40 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
2ca50 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
2ca60 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
2ca70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ca80 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
2ca90 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
2caa0 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
2cab0 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
2cac0 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
2cad0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2cae0 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
2caf0 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
2cb00 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
2cb10 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
2cb20 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
2cb30 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
2cb40 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
2cb50 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
2cb60 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
2cb70 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
2cb80 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
2cb90 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
2cba0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2cbb0 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
2cbc0 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
2cbd0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
2cbe0 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
2cbf0 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
2cc00 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
2cc10 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
2cc20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
2cc30 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
2cc40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cc50 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2cc60 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
2cc70 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
2cc80 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2cc90 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2cca0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
2ccb0 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
2ccc0 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
2ccd0 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
2cce0 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
2ccf0 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
2cd00 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  rruption..*/.SQL
2cd10 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2cd20 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
2cd30 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2cd40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2cd50 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
2cd60 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2cd70 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
2cd80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
2cd90 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2cda0 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
2cdb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cdc0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
2cdd0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2cde0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
2cdf0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
2ce00 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
2ce10 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
2ce20 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
2ce30 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
2ce40 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
2ce50 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2ce60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2ce70 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
2ce80 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
2ce90 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
2cea0 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
2ceb0 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
2cec0 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
2ced0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2cee0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
2cef0 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
2cf00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
2cf10 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
2cf20 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
2cf30 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
2cf40 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2cf50 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2cf60 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2cf70 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2cf80 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
2cf90 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2cfa0 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
2cfb0 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
2cfc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2cfd0 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
2cfe0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
2cff0 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
2d000 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2d010 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2d020 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
2d030 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2d040 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2d050 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2d060 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2d070 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
2d080 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
2d090 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
2d0a0 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2d0b0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2d0c0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
2d0d0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
2d0e0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2d0f0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
2d100 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
2d110 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
2d120 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
2d130 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
2d140 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d150 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nt] S..*/.SQLITE
2d160 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2d170 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
2d180 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2d190 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
2d1a0 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
2d1b0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
2d1c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
2d1d0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
2d1e0 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
2d1f0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
2d200 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2d210 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
2d220 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
2d230 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2d240 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
2d250 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2d260 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
2d270 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
2d280 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2d290 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
2d2a0 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
2d2b0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2d2c0 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
2d2d0 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
2d2e0 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
2d2f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2d300 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
2d310 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
2d320 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
2d330 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2d340 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
2d350 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
2d360 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
2d370 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
2d380 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
2d390 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
2d3a0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
2d3b0 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
2d3c0 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
2d3d0 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
2d3e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2d3f0 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
2d400 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
2d410 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2d420 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2d430 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
2d440 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
2d450 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
2d460 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
2d470 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
2d480 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
2d490 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
2d4a0 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
2d4b0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2d4c0 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
2d4d0 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
2d4e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2d4f0 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
2d500 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
2d510 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2d520 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2d530 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
2d540 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
2d550 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
2d560 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
2d570 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
2d580 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
2d590 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
2d5a0 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
2d5b0 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
2d5c0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
2d5d0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
2d5e0 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
2d5f0 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
2d600 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
2d610 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
2d620 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
2d630 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
2d640 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
2d650 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
2d660 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
2d670 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2d680 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
2d690 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
2d6a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
2d6b0 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
2d6c0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2d6d0 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
2d6e0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2d6f0 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
2d700 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
2d710 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
2d720 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2d730 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
2d740 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
2d750 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2d760 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
2d770 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
2d780 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
2d790 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
2d7a0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
2d7b0 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
2d7c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
2d7d0 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
2d7e0 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
2d7f0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2d800 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
2d810 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
2d820 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
2d830 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
2d840 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
2d850 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
2d860 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
2d870 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
2d880 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
2d890 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79  rameters.  Every
2d8a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
2d8b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
2d8c0 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72  t be able to wor
2d8d0 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c  k.** with UTF-8,
2d8e0 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
2d8f0 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
2d900 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2d910 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
2d920 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
2d930 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
2d940 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20  n another.  ^An 
2d950 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a  application may.
2d960 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
2d970 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2d980 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
2d990 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2d9a0 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
2d9b0 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
2d9c0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
2d9d0 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
2d9e0 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
2d9f0 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  p..** ^When mult
2da00 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2da10 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2da20 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
2da30 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
2da40 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
2da50 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
2da60 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
2da70 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
2da80 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  ersion..** If th
2da90 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69  ere is only a si
2daa0 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ngle implementat
2dab0 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e  ion which does n
2dac0 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78  ot care what tex
2dad0 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73  t.** encoding is
2dae0 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
2daf0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
2db00 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54  should be [SQLIT
2db10 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  E_ANY]..**.** ^(
2db20 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
2db30 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
2db40 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
2db50 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2db60 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
2db70 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
2db80 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
2db90 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
2dba0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
2dbb0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
2dbc0 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
2dbd0 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
2dbe0 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
2dbf0 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
2dc00 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
2dc10 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
2dc20 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
2dc30 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2dc40 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2dc50 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
2dc60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
2dc70 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
2dc80 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
2dc90 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
2dca0 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
2dcb0 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
2dcc0 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
2dcd0 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
2dce0 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
2dcf0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2dd00 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
2dd10 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2dd20 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
2dd30 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
2dd40 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
2dd50 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
2dd60 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
2dd70 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
2dd80 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2dd90 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
2dda0 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
2ddb0 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
2ddc0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
2ddd0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
2dde0 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
2ddf0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
2de00 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
2de10 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
2de20 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
2de30 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
2de40 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
2de50 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
2de60 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
2de70 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
2de80 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
2de90 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
2dea0 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
2deb0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
2dec0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ded0 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
2dee0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
2def0 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
2df00 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
2df10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2df20 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
2df30 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
2df40 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
2df50 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
2df60 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
2df70 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
2df80 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
2df90 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
2dfa0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
2dfb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2dfc0 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
2dfd0 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
2dfe0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2dff0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2e000 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
2e010 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
2e020 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
2e030 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2e040 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2e050 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
2e060 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2e070 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
2e080 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
2e090 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
2e0a0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
2e0b0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
2e0c0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
2e0d0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
2e0e0 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
2e0f0 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
2e100 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
2e110 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
2e120 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
2e130 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
2e140 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
2e150 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
2e160 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
2e170 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
2e180 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
2e190 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
2e1a0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2e1b0 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
2e1c0 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
2e1d0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2e1e0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2e1f0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
2e200 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
2e210 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
2e220 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
2e230 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
2e240 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2e250 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
2e260 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
2e270 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
2e280 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
2e290 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
2e2a0 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
2e2b0 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
2e2c0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
2e2d0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
2e2e0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
2e2f0 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
2e300 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
2e310 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
2e320 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
2e330 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
2e340 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
2e350 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
2e360 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
2e370 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2e380 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
2e390 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
2e3a0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
2e3b0 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
2e3c0 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
2e3d0 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
2e3e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2e3f0 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
2e400 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
2e410 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
2e420 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
2e430 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
2e440 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
2e450 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2e460 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2e470 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
2e480 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
2e490 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2e4a0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2e4b0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2e4c0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2e4d0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2e4e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2e4f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2e500 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2e510 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2e520 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2e530 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2e540 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2e550 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53  3_context*).);.S
2e560 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2e570 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2e580 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
2e590 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2e5a0 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
2e5b0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2e5c0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2e5d0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2e5e0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2e5f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2e600 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2e610 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2e620 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2e630 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2e640 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2e650 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2e660 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
2e670 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2e680 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2e690 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
2e6a0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
2e6b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
2e6c0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
2e6d0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
2e6e0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
2e6f0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
2e700 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2e710 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2e720 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2e730 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
2e740 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2e750 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2e760 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
2e770 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
2e780 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
2e790 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
2e7a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e7b0 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
2e7c0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
2e7d0 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
2e7e0 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
2e7f0 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
2e800 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
2e810 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
2e820 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
2e830 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e840 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
2e850 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e860 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
2e870 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e880 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
2e890 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e8a0 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
2e8b0 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
2e8c0 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
2e8d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
2e8e0 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
2e8f0 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
2e900 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e  eate_function on
2e910 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
2e920 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
2e930 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
2e940 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2e950 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
2e960 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2e970 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
2e980 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
2e990 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
2e9a0 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
2e9b0 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
2e9c0 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
2e9d0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
2e9e0 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
2e9f0 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
2ea00 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
2ea10 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
2ea20 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
2ea30 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
2ea40 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
2ea50 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
2ea60 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
2ea70 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
2ea80 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
2ea90 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
2eaa0 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
2eab0 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
2eac0 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74   tell you what t
2ead0 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
2eae0 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
2eaf0 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
2eb00 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
2eb10 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2eb20 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
2eb30 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
2eb40 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
2eb50 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
2eb60 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
2eb70 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
2eb80 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
2eb90 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
2eba0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2ebb0 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
2ebc0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2ebd0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
2ebe0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
2ebf0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2ec00 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
2ec10 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
2ec20 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
2ec30 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
2ec40 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
2ec50 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
2ec60 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
2ec70 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2ec80 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
2ec90 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
2eca0 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2ecb0 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c  4,int),void*,sql
2ecc0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
2ecd0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2ece0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
2ecf0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
2ed00 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
2ed10 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
2ed20 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2ed30 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
2ed40 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
2ed50 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
2ed60 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
2ed70 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
2ed80 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
2ed90 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
2eda0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2edb0 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
2edc0 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
2edd0 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
2ede0 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
2edf0 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
2ee00 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
2ee10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ee20 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
2ee30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ee40 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
2ee50 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
2ee60 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
2ee70 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
2ee80 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
2ee90 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
2eea0 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
2eeb0 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
2eec0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
2eed0 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
2eee0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2eef0 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
2ef00 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
2ef10 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
2ef20 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
2ef30 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
2ef40 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
2ef50 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
2ef60 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
2ef70 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
2ef80 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2ef90 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
2efa0 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
2efb0 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
2efc0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2efd0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
2efe0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
2eff0 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
2f000 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
2f010 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2f020 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
2f030 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
2f040 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
2f050 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2f060 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
2f070 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
2f080 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
2f090 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
2f0a0 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
2f0b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
2f0c0 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
2f0d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2f0e0 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
2f0f0 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
2f100 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
2f110 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
2f120 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
2f130 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
2f140 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2f150 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
2f160 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
2f170 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
2f180 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
2f190 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
2f1a0 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
2f1b0 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
2f1c0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
2f1d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
2f1e0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
2f1f0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
2f200 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
2f210 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
2f220 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
2f230 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
2f240 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
2f250 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
2f260 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
2f270 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
2f280 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
2f290 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
2f2a0 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
2f2b0 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
2f2c0 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
2f2d0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
2f2e0 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
2f2f0 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
2f300 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
2f310 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
2f320 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
2f330 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
2f340 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
2f350 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
2f360 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
2f370 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
2f380 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
2f390 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
2f3a0 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
2f3b0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
2f3c0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
2f3d0 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
2f3e0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
2f3f0 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
2f400 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
2f410 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
2f420 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
2f430 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
2f440 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
2f450 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
2f460 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
2f470 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
2f480 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2f490 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
2f4a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2f4b0 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
2f4c0 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
2f4d0 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
2f4e0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2f4f0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
2f500 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2f510 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
2f520 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2f530 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
2f540 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2f550 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
2f560 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
2f570 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2f580 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
2f590 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
2f5a0 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
2f5b0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
2f5c0 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
2f5d0 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
2f5e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2f5f0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
2f600 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f610 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2f620 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2f630 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
2f640 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
2f650 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2f660 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
2f670 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2f680 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c  E_API double sql
2f690 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
2f6a0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2f6b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2f6c0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2f6d0 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
2f6e0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
2f6f0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2f700 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
2f710 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
2f720 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2f730 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
2f740 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
2f750 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
2f760 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
2f770 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2f780 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2f790 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2f7a0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
2f7b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2f7c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2f7d0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2f7e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2f7f0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2f800 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
2f810 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2f820 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2f830 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2f840 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2f850 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
2f860 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2f870 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
2f880 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2f890 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f8a0 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
2f8b0 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
2f8c0 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
2f8d0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
2f8e0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2f8f0 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
2f900 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
2f910 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
2f920 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
2f930 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
2f940 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
2f950 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2f960 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
2f970 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
2f980 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
2f990 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
2f9a0 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
2f9b0 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
2f9c0 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
2f9d0 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
2f9e0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2f9f0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
2fa00 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
2fa10 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
2fa20 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
2fa30 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
2fa40 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
2fa50 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
2fa60 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
2fa70 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
2fa80 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
2fa90 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
2faa0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2fab0 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
2fac0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
2fad0 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
2fae0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
2faf0 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
2fb00 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
2fb10 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
2fb20 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
2fb30 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
2fb40 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
2fb50 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
2fb60 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
2fb70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
2fb80 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
2fb90 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
2fba0 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
2fbb0 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
2fbc0 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
2fbd0 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
2fbe0 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
2fbf0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2fc00 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
2fc10 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
2fc20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
2fc30 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
2fc40 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
2fc50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
2fc60 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2fc70 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
2fc80 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
2fc90 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65  er if N is.** le
2fca0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
2fcb0 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
2fcc0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
2fcd0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
2fce0 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
2fcf0 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
2fd00 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
2fd10 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2fd20 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
2fd30 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
2fd40 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
2fd50 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
2fd60 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
2fd70 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
2fd80 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
2fd90 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
2fda0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2fdb0 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
2fdc0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
2fdd0 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
2fde0 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
2fdf0 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
2fe00 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  allocation.)^.**
2fe10 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
2fe20 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
2fe30 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
2fe40 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
2fe50 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2fe60 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
2fe70 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
2fe80 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
2fe90 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
2fea0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
2feb0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
2fec0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2fed0 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
2fee0 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
2fef0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
2ff00 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
2ff10 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
2ff20 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
2ff30 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2ff40 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
2ff50 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2ff60 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
2ff70 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2ff80 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2ff90 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2ffa0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2ffb0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2ffc0 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
2ffd0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
2ffe0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2fff0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
30000 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
30010 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30020 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
30030 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
30040 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
30050 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
30060 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
30070 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
30080 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
30090 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
300a0 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
300b0 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
300c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
300d0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
300e0 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
300f0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
30100 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
30110 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
30120 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
30130 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
30140 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
30150 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
30160 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
30170 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
30180 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
30190 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
301a0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
301b0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
301c0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
301d0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
301e0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
301f0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
30200 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
30210 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
30220 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
30230 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
30240 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
30250 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
30260 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
30270 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
30280 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
30290 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
302a0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
302b0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
302c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
302d0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
302e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
302f0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
30300 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
30310 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
30320 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
30330 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
30340 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
30350 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
30360 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
30370 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30380 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
30390 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
303a0 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
303b0 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
303c0 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
303d0 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
303e0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
303f0 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
30400 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
30410 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
30420 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
30430 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
30440 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
30450 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
30460 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
30470 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
30480 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
30490 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
304a0 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
304b0 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
304c0 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
304d0 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
304e0 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
304f0 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
30500 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
30510 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
30520 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
30530 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
30540 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
30550 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
30560 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
30570 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
30580 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
30590 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
305a0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
305b0 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
305c0 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
305d0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
305e0 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
305f0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
30600 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
30610 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
30620 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
30630 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
30640 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
30650 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
30660 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
30670 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
30680 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
30690 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
306a0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
306b0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
306c0 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
306d0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
306e0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
306f0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
30700 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
30710 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
30720 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30730 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
30740 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
30750 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
30760 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
30770 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
30780 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
30790 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
307a0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
307b0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
307c0 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
307d0 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
307e0 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
307f0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
30800 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
30810 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
30820 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
30830 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
30840 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
30850 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
30860 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
30870 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
30880 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
30890 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
308a0 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
308b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
308c0 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
308d0 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
308e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
308f0 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
30900 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
30910 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
30920 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
30930 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20  * ^If it is not 
30940 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
30950 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
30960 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
30970 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
30980 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
30990 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
309a0 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
309b0 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
309c0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
309d0 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
309e0 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
309f0 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
30a00 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
30a10 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
30a20 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
30a30 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
30a40 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
30a50 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
30a60 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
30a70 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
30a80 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
30a90 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65   any time.  ^The
30aa0 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20   only guarantee 
30ab0 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64  is that.** the d
30ac0 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62  estructor will b
30ad0 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
30ae0 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
30af0 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  dropped..**.** ^
30b00 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
30b10 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
30b20 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
30b30 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
30b40 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
30b50 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
30b60 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
30b70 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
30b80 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
30b90 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
30ba0 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].)^.**.** These
30bb0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
30bc0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
30bd0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
30be0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
30bf0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
30c00 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
30c10 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
30c20 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
30c30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30c40 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f   int N);.SQLITE_
30c50 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
30c60 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
30c70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
30c80 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
30c90 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
30ca0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30cb0 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
30cc0 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
30cd0 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a  ructor Behavior.
30ce0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
30cf0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
30d00 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
30d10 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
30d20 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
30d30 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
30d40 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
30d50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
30d60 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20  ob()].  ^If the 
30d70 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
30d80 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
30d90 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
30da0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
30db0 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
30dc0 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
30dd0 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
30de0 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
30df0 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
30e00 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c  ed.  ^The.** SQL
30e10 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
30e20 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
30e30 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
30e40 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
30e50 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
30e60 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
30e70 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
30e80 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
30e90 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
30ea0 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
30eb0 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
30ec0 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
30ed0 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
30ee0 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
30ef0 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
30f00 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
30f10 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
30f20 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
30f30 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
30f40 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
30f50 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
30f60 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
30f70 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
30f80 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
30f90 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
30fa0 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
30fb0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
30fc0 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
30fd0 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
30fe0 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
30ff0 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
31000 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
31010 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
31020 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
31030 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
31040 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
31050 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
31060 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
31070 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
31080 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
31090 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
310a0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
310b0 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
310c0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
310d0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
310e0 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
310f0 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
31100 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
31110 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
31120 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
31130 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
31140 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
31150 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
31160 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
31170 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
31180 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
31190 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
311a0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
311b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
311c0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
311d0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
311e0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
311f0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
31200 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31210 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
31220 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
31230 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
31240 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
31250 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
31260 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
31270 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
31280 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
31290 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
312a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
312b0 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
312c0 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
312d0 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
312e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
312f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
31300 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
31310 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
31320 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
31330 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
31340 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
31350 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
31360 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
31370 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31380 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
31390 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
313a0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
313b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
313c0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
313d0 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
313e0 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
313f0 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
31400 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
31410 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
31420 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
31430 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31440 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
31450 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
31460 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
31470 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
31480 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
31490 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
314a0 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
314b0 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
314c0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
314d0 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
314e0 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
314f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31500 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
31510 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
31520 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
31530 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
31540 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
31550 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
31560 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31570 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
31580 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
31590 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
315a0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
315b0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
315c0 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
315d0 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
315e0 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
315f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
31600 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31610 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
31620 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
31630 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
31640 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
31650 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
31660 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
31670 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
31680 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
31690 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
316a0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
316b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
316c0 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
316d0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
316e0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
316f0 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
31700 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
31710 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
31720 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
31730 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
31740 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
31750 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
31760 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
31770 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
31780 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31790 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
317a0 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
317b0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
317c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
317d0 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
317e0 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
317f0 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
31800 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
31810 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
31820 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
31830 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
31840 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
31850 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
31860 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
31870 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
31880 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
31890 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
318a0 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
318b0 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
318c0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
318d0 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
318e0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
318f0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
31900 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
31910 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
31920 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
31930 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
31940 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
31950 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
31960 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
31970 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
31980 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f  lite3_result_too
31990 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
319a0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
319b0 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
319c0 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
319d0 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
319e0 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
319f0 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
31a00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31a10 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20  _result_nomem() 
31a20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
31a30 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
31a40 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
31a50 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
31a60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
31a70 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
31a80 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31a90 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
31aa0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
31ab0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
31ac0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31ad0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31ae0 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
31af0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
31b00 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
31b10 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
31b20 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
31b30 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
31b40 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
31b50 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
31b60 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
31b70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31b80 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
31b90 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
31ba0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
31bb0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
31bc0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
31bd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31be0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
31bf0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
31c00 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
31c10 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
31c20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31c30 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
31c40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31c50 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31c60 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
31c70 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
31c80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31c90 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
31ca0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31cb0 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
31cc0 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
31cd0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
31ce0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31cf0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31d00 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
31d10 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
31d20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
31d30 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
31d40 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
31d50 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
31d60 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
31d70 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
31d80 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
31d90 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
31da0 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
31db0 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
31dc0 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
31dd0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
31de0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
31df0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
31e00 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
31e10 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
31e20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
31e30 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
31e40 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
31e50 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
31e60 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
31e70 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
31e80 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
31e90 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
31ea0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
31eb0 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
31ec0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
31ed0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31ee0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
31ef0 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
31f00 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
31f10 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
31f20 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
31f30 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
31f40 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
31f50 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
31f60 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
31f70 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
31f80 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a  nction result..*
31f90 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
31fa0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
31fb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31fc0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
31fd0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
31fe0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
31ff0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
32000 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
32010 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
32020 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
32030 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
32040 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
32050 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
32060 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
32070 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
32080 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
32090 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
320a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
320b0 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
320c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
320d0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
320e0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
320f0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
32100 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
32110 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
32120 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
32130 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
32140 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
32150 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
32160 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
32170 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
32180 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
32190 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
321a0 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
321b0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
321c0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
321d0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
321e0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
321f0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
32200 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
32210 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
32220 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
32230 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
32240 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
32250 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
32260 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
32270 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
32280 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
32290 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
322a0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
322b0 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
322c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
322d0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
322e0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
322f0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
32300 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
32310 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
32320 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
32330 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
32340 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
32350 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
32360 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
32370 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a  ameter.  ^The.**
32380 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32390 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
323a0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
323b0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
323c0 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
323d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
323e0 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
323f0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
32400 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
32410 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
32420 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
32430 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
32440 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
32450 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63  m..** ^A [protec
32460 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
32470 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
32480 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
32490 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
324a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
324b0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
324c0 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
324d0 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
324e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
324f0 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
32500 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
32510 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
32520 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
32530 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
32540 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
32550 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
32560 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
32570 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
32580 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32590 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
325a0 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
325b0 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
325c0 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
325d0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
325e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
325f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32600 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
32610 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
32620 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
32630 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
32640 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
32650 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
32660 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
32670 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51  xt*, double);.SQ
32680 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
32690 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
326a0 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
326b0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
326c0 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
326d0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
326e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
326f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32700 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
32710 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
32720 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32730 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
32740 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
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 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
32780 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
32790 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
327a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
327b0 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
327c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
327d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
327e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
327f0 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
32800 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51  ntext*, int);.SQ
32810 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
32820 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
32830 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
32840 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
32850 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
32860 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32870 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
32880 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
32890 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
328a0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
328b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
328c0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
328d0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
328e0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
328f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32900 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
32910 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
32920 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
32930 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
32940 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
32950 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32960 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
32970 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
32980 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
32990 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
329a0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
329b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
329c0 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
329d0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
329e0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
329f0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
32a00 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
32a10 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
32a20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
32a30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32a40 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
32a50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
32a60 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
32a70 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
32a80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32a90 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
32aa0 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
32ab0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  s.**.** ^These f
32ac0 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65  unctions add, re
32ad0 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20  move, or modify 
32ae0 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73  a [collation] as
32af0 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
32b00 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
32b10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
32b20 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
32b30 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
32b40 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
32b50 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  he collation is 
32b60 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
32b70 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
32b80 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
32b90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
32ba0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
32bb0 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
32bc0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
32bd0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
32be0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
32bf0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
32c00 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e  .** ^Collation n
32c10 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72  ames that compar
32c20 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e  e equal accordin
32c30 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  g to [sqlite3_st
32c40 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a  rnicmp()] are.**
32c50 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62   considered to b
32c60 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  e the same name.
32c70 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69  .**.** ^(The thi
32c80 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65  rd argument (eTe
32c90 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f  xtRep) must be o
32ca0 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
32cb0 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  nts:.** <ul>.** 
32cc0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
32cd0 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8],.** <li> [SQL
32ce0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a  ITE_UTF16LE],.**
32cf0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
32d00 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16BE],.** <li> 
32d10 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
32d20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
32d30 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
32d40 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  ]..** </ul>)^.**
32d50 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61   ^The eTextRep a
32d60 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e  rgument determin
32d70 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  es the encoding 
32d80 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65  of strings passe
32d90 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c  d.** to the coll
32da0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
32db0 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61  allback, xCallba
32dc0 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  ck..** ^The [SQL
32dd0 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b  ITE_UTF16] and [
32de0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
32df0 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72  GNED] values for
32e00 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72   eTextRep.** for
32e10 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  ce strings to be
32e20 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69   UTF16 with nati
32e30 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
32e40 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
32e50 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
32e60 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70  lue for eTextRep
32e70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20   forces strings 
32e80 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61  to begin.** on a
32e90 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72  n even byte addr
32ea0 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ess..**.** ^The 
32eb0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
32ec0 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70   pArg, is an app
32ed0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
32ee0 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61  inter that is pa
32ef0 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20  ssed.** through 
32f00 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
32f10 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c  ument to the col
32f20 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
32f30 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
32f40 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
32f50 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20  ent, xCallback, 
32f60 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
32f70 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
32f80 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74  nction..** ^Mult
32f90 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  iple collating f
32fa0 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20  unctions can be 
32fb0 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
32fc0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
32fd0 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65  ut.** with diffe
32fe0 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61  rent eTextRep pa
32ff0 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c  rameters and SQL
33000 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69  ite will use whi
33010 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69  chever.** functi
33020 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20  on requires the 
33030 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
33040 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74  data transformat
33050 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
33060 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65  xCallback argume
33070 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  nt is NULL then 
33080 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
33090 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c  nction is.** del
330a0 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c  eted.  ^When all
330b0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
330c0 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20  ions having the 
330d0 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65  same name are de
330e0 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63  leted,.** that c
330f0 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c  ollation is no l
33100 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a  onger usable..**
33110 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69  .** ^The collati
33120 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
33130 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
33140 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74  with a copy of t
33150 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c  he pArg .** appl
33160 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
33170 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77  nter and with tw
33180 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65  o strings in the
33190 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66   encoding specif
331a0 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54  ied.** by the eT
331b0 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e  extRep argument.
331c0 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20    The collating 
331d0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65  function must re
331e0 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  turn an.** integ
331f0 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74  er that is negat
33200 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f  ive, zero, or po
33210 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65  sitive.** if the
33220 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
33230 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61   less than, equa
33240 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
33250 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
33260 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ,.** respectivel
33270 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  y.  A collating 
33280 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c  function must al
33290 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
332a0 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67  same answer.** g
332b0 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e  iven the same in
332c0 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72  puts.  If two or
332d0 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20   more collating 
332e0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65  functions are re
332f0 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74  gistered.** to t
33300 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f  he same collatio
33310 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69  n name (using di
33320 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
33330 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c   values) then al
33340 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61  l.** must give a
33350 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73  n equivalent ans
33360 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64  wer when invoked
33370 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74   with equivalent
33380 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
33390 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
333a0 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68  ion must obey th
333b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70  e following prop
333c0 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a  erties for all.*
333d0 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20  * strings A, B, 
333e0 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c  and C:.**.** <ol
333f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  >.** <li> If A==
33400 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20  B then B==A..** 
33410 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64  <li> If A==B and
33420 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e   B==C then A==C.
33430 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
33440 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a  ;B THEN B&gt;A..
33450 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b  ** <li> If A&lt;
33460 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65  B and B&lt;C the
33470 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f  n A&lt;C..** </o
33480 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f  l>.**.** If a co
33490 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
334a0 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68   fails any of th
334b0 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69  e above constrai
334c0 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20  nts and that.** 
334d0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
334e0 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65  on is  registere
334f0 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e  d and used, then
33500 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
33510 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e   SQLite.** is un
33520 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
33530 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
33540 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
33550 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
33560 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33570 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20  ation().** with 
33580 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61  the addition tha
33590 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63  t the xDestroy c
335a0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
335b0 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a  ed on pArg when.
335c0 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** the collating
335d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
335e0 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  eted..** ^Collat
335f0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
33600 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  e deleted when t
33610 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64  hey are overridd
33620 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63  en by later.** c
33630 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c  alls to the coll
33640 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66  ation creation f
33650 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e  unctions or when
33660 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
33670 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
33680 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73   closed using [s
33690 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
336a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73  .**.** ^The xDes
336b0 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
336c0 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c   <u>not</u> call
336d0 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71  ed if the .** sq
336e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
336f0 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63  lation_v2() func
33700 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70  tion fails.  App
33710 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69  lications that i
33720 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
33730 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
33740 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f  n_v2() with a no
33750 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20  n-NULL xDestroy 
33760 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
33770 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65  .** check the re
33780 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69  turn code and di
33790 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70  spose of the app
337a0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
337b0 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c  inter.** themsel
337c0 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20  ves rather than 
337d0 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65  expecting SQLite
337e0 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74   to deal with it
337f0 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68   for them..** Th
33800 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20  is is different 
33810 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72  from every other
33820 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
33830 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73  e.  The inconsis
33840 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66  tency .** is unf
33850 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e  ortunate but can
33860 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77  not be changed w
33870 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
33880 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f  backwards .** co
33890 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
338a0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73  ** See also:  [s
338b0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
338c0 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b  _needed()] and [
338d0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
338e0 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a  n_needed16()]..*
338f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
33900 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33910 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
33920 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
33930 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
33940 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
33950 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
33960 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
33970 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
33980 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
33990 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  id*).);.SQLITE_A
339a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
339b0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
339c0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
339d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
339e0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
339f0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
33a00 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
33a10 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
33a20 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
33a30 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20  ,const void*),. 
33a40 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
33a50 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54  (void*).);.SQLIT
33a60 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
33a70 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33a80 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
33a90 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
33aa0 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
33ab0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
33ac0 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
33ad0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
33ae0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
33af0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
33b00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33b10 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
33b20 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ded Callbacks.**
33b30 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61  .** ^To avoid ha
33b40 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
33b50 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
33b60 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
33b70 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
33b80 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
33b90 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
33ba0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
33bb0 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
33bc0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
33bd0 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
33be0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
33bf0 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
33c00 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
33c10 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e  nce is required.
33c20 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
33c30 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
33c40 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
33c50 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33c60 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
33c70 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
33c80 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
33c90 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
33ca0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
33cb0 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
33cc0 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
33cd0 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ^If sqlite3_coll
33ce0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
33cf0 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
33d00 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
33d10 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
33d20 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
33d30 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20  te order..** ^A 
33d40 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
33d50 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
33d60 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f   the existing co
33d70 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63  llation-needed c
33d80 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
33d90 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  (When the callba
33da0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
33db0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
33dc0 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
33dd0 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
33de0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
33df0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33e00 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
33e10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
33e20 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
33e30 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
33e40 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
33e50 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
33e60 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
33e70 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
33e80 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
33e90 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
33ea0 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
33eb0 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
33ec0 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
33ed0 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
33ee0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
33ef0 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
33f00 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
33f10 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
33f20 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
33f30 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
33f40 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
33f50 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ence.)^.**.** Th
33f60 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
33f70 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
33f80 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
33f90 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
33fa0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
33fb0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
33fc0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33fd0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
33fe0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
33ff0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34000 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  _v2()]..*/.SQLIT
34010 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
34020 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
34030 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
34040 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
34050 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
34060 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
34070 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
34080 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
34090 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
340a0 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71  n_needed16(.  sq
340b0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
340c0 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ,.  void(*)(void
340d0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
340e0 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f  TextRep,const vo
340f0 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20  id*).);..#ifdef 
34100 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43  SQLITE_HAS_CODEC
34110 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
34120 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e  he key for an en
34130 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65  crypted database
34140 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
34150 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c  should be.** cal
34160 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20  led right after 
34170 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
34180 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
34190 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
341a0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
341b0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
341c0 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
341d0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
341e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
341f0 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
34200 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
34210 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
34220 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
34230 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
34240 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
34250 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
34260 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
34270 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
34280 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
34290 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
342a0 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
342b0 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
342c0 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
342d0 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
342e0 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
342f0 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
34300 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
34310 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
34320 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
34330 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
34340 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
34350 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
34360 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
34370 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
34380 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28  t sqlite3_rekey(
34390 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
343a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
343b0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
343c0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
343d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
343e0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
343f0 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a  /* The new key *
34400 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  /.);../*.** Spec
34410 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
34420 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45  on key for a SEE
34430 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
34440 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
34450 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45  , none of the SE
34460 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  E routines will 
34470 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  work..*/.SQLITE_
34480 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
34490 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20  _activate_see(. 
344a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
344b0 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
344c0 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
344d0 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
344e0 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  f..#ifdef SQLITE
344f0 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a  _ENABLE_CEROD./*
34500 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
34510 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
34520 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62  or a CEROD datab
34530 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
34540 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
34550 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f   of the CEROD ro
34560 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
34570 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
34580 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
34590 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63  ivate_cerod(.  c
345a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
345b0 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
345c0 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
345d0 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
345e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
345f0 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
34600 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
34610 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ime.**.** The sq
34620 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75  lite3_sleep() fu
34630 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68  nction causes th
34640 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
34650 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
34660 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
34670 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
34680 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
34690 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
346a0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
346b0 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   If the operatin
346c0 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
346d0 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
346e0 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a  requests with.**
346f0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d   millisecond tim
34700 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68  e resolution, th
34710 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c  en the time will
34720 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74   be rounded up t
34730 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74  o.** the nearest
34740 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d   second. The num
34750 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
34760 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
34770 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74  ually.** request
34780 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
34790 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
347a0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
347b0 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e  ^SQLite implemen
347c0 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
347d0 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
347e0 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
347f0 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
34800 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
34810 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65   object.  If the
34820 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
34830 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75  .** of the defau
34840 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d  lt VFS is not im
34850 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63  plemented correc
34860 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c  tly, or not impl
34870 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c  emented at.** al
34880 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  l, then the beha
34890 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
348a0 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 69  sleep() may devi
348b0 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73  ate from the des
348c0 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74  cription.** in t
348d0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
348e0 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49 54  graphs..*/.SQLIT
348f0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
34900 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
34910 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
34920 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
34930 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
34940 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
34950 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
34960 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
34970 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
34980 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
34990 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
349a0 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
349b0 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
349c0 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
349d0 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
349e0 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  by SQLite when u
349f0 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
34a00 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
34a10 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70  FS].** will be p
34a20 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
34a30 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20  rectory.)^  ^If 
34a40 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
34a50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
34a60 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
34a70 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
34a80 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
34a90 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
34aa0 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
34ab0 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
34ac0 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
34ad0 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
34ae0 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
34af0 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
34b00 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
34b10 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
34b20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
34b30 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
34b40 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
34b50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
34b60 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
34b70 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
34b80 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
34b90 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
34ba0 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
34bb0 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
34bc0 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
34bd0 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
34be0 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
34bf0 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
34c00 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
34c10 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
34c20 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
34c30 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
34c40 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
34c50 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
34c60 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74  ** ^The [temp_st
34c70 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
34c80 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
34c90 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
34ca0 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
34cb0 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
34cc0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
34cd0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
34ce0 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
34cf0 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74  .** the [temp_st
34d00 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
34d10 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
34d20 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
34d30 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
34d40 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
34d50 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
34d60 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
34d70 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
34d80 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
34d90 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
34da0 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
34db0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
34dc0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
34dd0 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
34de0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
34df0 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
34e00 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
34e10 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
34e20 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
34e30 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
34e40 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
34e50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
34e60 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
34e70 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74   of the [temp_st
34e80 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
34e90 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
34ea0 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
34eb0 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
34ec0 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
34ed0 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ory;../*.** CAPI
34ee0 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41  3REF: Test For A
34ef0 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a  uto-Commit Mode.
34f00 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75  ** KEYWORDS: {au
34f10 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a  tocommit mode}.*
34f20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34f30 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
34f40 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
34f50 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
34f60 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
34f70 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
34f80 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
34f90 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
34fa0 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
34fb0 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75  spectively.  ^Au
34fc0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
34fd0 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a   on by default..
34fe0 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  ** ^Autocommit m
34ff0 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
35000 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61  by a [BEGIN] sta
35010 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f  tement..** ^Auto
35020 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72  commit mode is r
35030 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b  e-enabled by a [
35040 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c  COMMIT] or [ROLL
35050 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  BACK]..**.** If 
35060 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66  certain kinds of
35070 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e   errors occur on
35080 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74   a statement wit
35090 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74  hin a multi-stat
350a0 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63  ement.** transac
350b0 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63  tion (errors inc
350c0 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  luding [SQLITE_F
350d0 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f  ULL], [SQLITE_IO
350e0 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ERR],.** [SQLITE
350f0 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45  _NOMEM], [SQLITE
35100 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c  _BUSY], and [SQL
35110 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20  ITE_INTERRUPT]) 
35120 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e  then the.** tran
35130 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  saction might be
35140 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
35150 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
35160 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20   only way to.** 
35170 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72  find out whether
35180 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
35190 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
351a0 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
351b0 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72  n after.** an er
351c0 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68  ror is to use th
351d0 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
351e0 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  ** If another th
351f0 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65  read changes the
35200 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74   autocommit stat
35210 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  us of the databa
35220 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
35230 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74   while this rout
35240 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20  ine is running, 
35250 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
35260 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65  value.** is unde
35270 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  fined..*/.SQLITE
35280 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
35290 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
352a0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
352b0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
352c0 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61   The Database Ha
352d0 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72  ndle Of A Prepar
352e0 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
352f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35300 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66  db_handle interf
35310 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
35320 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35330 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
35340 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70  to which a [prep
35350 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
35360 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b  belongs.  ^The [
35370 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35380 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ion].** returned
35390 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68   by sqlite3_db_h
353a0 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d  andle is the sam
353b0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
353c0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20  ection].** that 
353d0 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72  was the first ar
353e0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
353f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
35400 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72  e_v2()] call (or
35410 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74   its variants) t
35420 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a  hat was used to.
35430 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74  ** create the st
35440 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66  atement in the f
35450 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 53  irst place..*/.S
35460 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
35470 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
35480 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
35490 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
354a0 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
354b0 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
354c0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
354d0 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
354e0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
354f0 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
35500 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
35510 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
35520 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
35530 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
35540 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
35550 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
35560 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
35570 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35580 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
35590 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
355a0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
355b0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
355c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
355d0 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
355e0 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
355f0 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
35600 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
35610 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
35620 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  , it returns NUL
35630 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61  L..**.** The [da
35640 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35650 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20  n] pointer D in 
35660 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
35670 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
35680 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72  D,S)] must refer
35690 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   to an open data
356a0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
356b0 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63  on and in partic
356c0 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65  ular must not be
356d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
356e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  .*/.SQLITE_API s
356f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c  qlite3_stmt *sql
35700 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73  ite3_next_stmt(s
35710 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c  qlite3 *pDb, sql
35720 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
35730 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35740 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
35750 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
35760 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
35770 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35780 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
35790 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
357a0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
357b0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
357c0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
357d0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
357e0 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d  is [COMMIT | com
357f0 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79  mitted]..** ^Any
35800 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
35810 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
35820 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
35830 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
35840 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
35850 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
35860 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
35870 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c  ^The sqlite3_rol
35880 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
35890 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
358a0 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
358b0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
358c0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
358d0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
358e0 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c  [ROLLBACK | roll
358f0 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e  ed back]..** ^An
35900 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
35910 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
35920 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c  l to sqlite3_rol
35930 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  lback_hook().** 
35940 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
35950 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35960 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
35970 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67  ** ^The pArg arg
35980 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
35990 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
359a0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20  allback..** ^If 
359b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
359c0 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
359d0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
359e0 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  on-zero,.** then
359f0 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
35a00 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
35a10 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
35a20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
35a30 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  mit_hook(D,C,P) 
35a40 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  and sqlite3_roll
35a50 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  back_hook(D,C,P)
35a60 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
35a70 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d  turn the P argum
35a80 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
35a90 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68  vious call of th
35aa0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
35ab0 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
35ac0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35ad0 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
35ae0 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
35af0 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66   call for each f
35b00 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a  unction on D..**
35b10 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
35b20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35b30 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
35b40 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
35b50 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
35b60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35b70 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
35b80 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79  e callback.  Any
35b90 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
35ba0 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
35bb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
35bc0 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
35bd0 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
35be0 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
35bf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
35c00 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
35c10 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d  riggered the com
35c20 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61  mit.** or rollba
35c30 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66  ck hook in the f
35c40 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e  irst place..** N
35c50 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
35c60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
35c70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
35c80 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
35c90 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
35ca0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
35cb0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
35cc0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
35cd0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
35ce0 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67  .** ^Registering
35cf0 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
35d00 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
35d10 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57  llback..**.** ^W
35d20 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
35d30 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  ook callback rou
35d40 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
35d50 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a  o, the [COMMIT].
35d60 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  ** operation is 
35d70 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69  allowed to conti
35d80 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e  nue normally.  ^
35d90 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  If the commit ho
35da0 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f  ok.** returns no
35db0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
35dc0 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e   [COMMIT] is con
35dd0 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52  verted into a [R
35de0 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68  OLLBACK]..** ^Th
35df0 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  e rollback hook 
35e00 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20  is invoked on a 
35e10 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65  rollback that re
35e20 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d  sults from a com
35e30 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75  mit.** hook retu
35e40 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  rning non-zero, 
35e50 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64  just as it would
35e60 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68   be with any oth
35e70 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  er rollback..**.
35e80 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
35e90 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
35ea0 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
35eb0 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
35ec0 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  been.** rolled b
35ed0 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
35ee0 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
35ef0 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
35f00 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
35f10 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
35f20 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
35f30 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
35f40 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20   occur..** ^The 
35f50 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
35f60 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
35f70 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
35f80 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  n is.** automati
35f90 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
35fa0 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61  k because the da
35fb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35fc0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
35fd0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
35fe0 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
35ff0 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63  hook()] interfac
36000 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
36010 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
36020 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74  ommit_hook(sqlit
36030 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
36040 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
36050 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
36060 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
36070 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ok(sqlite3*, voi
36080 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f  d(*)(void *), vo
36090 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
360a0 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e  I3REF: Data Chan
360b0 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ge Notification 
360c0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
360d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64  ^The sqlite3_upd
360e0 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ate_hook() inter
360f0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
36100 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
36110 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
36120 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36130 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20  ion] identified 
36140 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
36150 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69  ument.** to be i
36160 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
36170 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  a row is updated
36180 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
36190 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63  leted..** ^Any c
361a0 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
361b0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
361c0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  o this function.
361d0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
361e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
361f0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
36200 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  n..**.** ^The se
36210 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
36220 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
36230 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e  e function to in
36240 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72  voke when a.** r
36250 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
36260 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
36270 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ed..** ^The firs
36280 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
36290 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  e callback is a 
362a0 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
362b0 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  d argument.** to
362c0 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
362d0 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20  hook()..** ^The 
362e0 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20  second callback 
362f0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
36300 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52  of [SQLITE_INSER
36310 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45  T], [SQLITE_DELE
36320 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  TE],.** or [SQLI
36330 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65  TE_UPDATE], depe
36340 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65  nding on the ope
36350 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73  ration that caus
36360 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  ed the callback.
36370 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
36380 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  ..** ^The third 
36390 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d  and fourth argum
363a0 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ents to the call
363b0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69  back contain poi
363c0 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20  nters to the.** 
363d0 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62  database and tab
363e0 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69  le name containi
363f0 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20  ng the affected 
36400 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e  row..** ^The fin
36410 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61  al callback para
36420 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f  meter is the [ro
36430 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e  wid] of the row.
36440 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65  .** ^In the case
36450 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74   of an update, t
36460 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69  his is the [rowi
36470 64 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64  d] after the upd
36480 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e  ate takes place.
36490 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64  .**.** ^(The upd
364a0 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20  ate hook is not 
364b0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74  invoked when int
364c0 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62  ernal system tab
364d0 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66  les are.** modif
364e0 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65  ied (i.e. sqlite
364f0 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69  _master and sqli
36500 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a  te_sequence).)^.
36510 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75  **.** ^In the cu
36520 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
36530 74 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65  tion, the update
36540 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20   hook.** is not 
36550 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70  invoked when dup
36560 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72  lication rows ar
36570 65 20 64 65 6c 65 74 65 64 20 62 65 63 61 75 73  e deleted becaus
36580 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43  e of an.** [ON C
36590 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e  ONFLICT | ON CON
365a0 46 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63  FLICT REPLACE] c
365b0 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20  lause.  ^Nor is 
365c0 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
365d0 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ** invoked when 
365e0 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
365f0 20 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e   using the [trun
36600 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
36610 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70  n]..** The excep
36620 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e  tions defined in
36630 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 20   this paragraph 
36640 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
36650 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65  a future.** rele
36660 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
36670 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20  *.** The update 
36680 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74  hook implementat
36690 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ion must not do 
366a0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
366b0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
366c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
366d0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
366e0 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  d the update hoo
366f0 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a  k.  Any actions.
36700 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ** to modify the
36710 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36720 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66  tion must be def
36730 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65  erred until afte
36740 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  r the.** complet
36750 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
36760 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
36770 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
36780 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e  the update hook.
36790 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
367a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
367b0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
367c0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
367d0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
367e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
367f0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
36800 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
36810 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
36820 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  h..**.** ^The sq
36830 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
36840 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f  k(D,C,P) functio
36850 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  n.** returns the
36860 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d   P argument from
36870 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
36880 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d  ll.** on the sam
36890 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
368a0 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55  ection] D, or NU
368b0 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69  LL for.** the fi
368c0 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a  rst call on D..*
368d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
368e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  e [sqlite3_commi
368f0 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73  t_hook()] and [s
36900 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
36910 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  hook()].** inter
36920 66 61 63 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  faces..*/.SQLITE
36930 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
36940 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a  e3_update_hook(.
36950 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
36960 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e  oid(*)(void *,in
36970 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c  t ,char const *,
36980 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c  char const *,sql
36990 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76  ite3_int64),.  v
369a0 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  oid*.);../*.** C
369b0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
369c0 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65  Or Disable Share
369d0 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a  d Pager Cache.**
369e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72   KEYWORDS: {shar
369f0 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20  ed cache}.**.** 
36a00 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65  ^(This routine e
36a10 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
36a20 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f  es the sharing o
36a30 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
36a40 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65  ache.** and sche
36a50 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ma data structur
36a60 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61  es between [data
36a70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
36a80 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a  | connections].*
36a90 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  * to the same da
36aa0 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20  tabase. Sharing 
36ab0 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
36ac0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72  e argument is tr
36ad0 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c  ue.** and disabl
36ae0 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
36af0 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a  nt is false.)^.*
36b00 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72  *.** ^Cache shar
36b10 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61  ing is enabled a
36b20 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20  nd disabled for 
36b30 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73  an entire proces
36b40 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  s..** This is a 
36b50 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c  change as of SQL
36b60 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
36b70 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73  0. In prior vers
36b80 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a  ions of SQLite,.
36b90 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65  ** sharing was e
36ba0 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
36bb0 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65  ed for each thre
36bc0 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  ad separately..*
36bd0 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65  *.** ^(The cache
36be0 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65   sharing mode se
36bf0 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  t by this interf
36c00 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20  ace effects all 
36c10 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  subsequent.** ca
36c20 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
36c30 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
36c40 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
36c50 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
36c60 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  6()]..** Existin
36c70 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  g database conne
36c80 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
36c90 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20  use the sharing 
36ca0 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73  mode.** that was
36cb0 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68   in effect at th
36cc0 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65  e time they were
36cd0 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a   opened.)^.**.**
36ce0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
36cf0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
36d00 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61  OK] if shared ca
36d10 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20  che was enabled 
36d20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73  or disabled.** s
36d30 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e  uccessfully.  An
36d40 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
36d50 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77   returned otherw
36d60 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68  ise.)^.**.** ^Sh
36d70 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
36d80 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
36d90 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68  t. But this migh
36da0 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66  t change in.** f
36db0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
36dc0 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69  f SQLite.  Appli
36dd0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72  cations that car
36de0 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a  e about shared.*
36df0 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20  * cache setting 
36e00 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78  should set it ex
36e10 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20  plicitly..**.** 
36e20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69  See Also:  [SQLi
36e30 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20  te Shared-Cache 
36e40 4d 6f 64 65 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Mode].*/.SQLITE_
36e50 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
36e60 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
36e70 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  che(int);../*.**
36e80 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d   CAPI3REF: Attem
36e90 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20  pt To Free Heap 
36ea0 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  Memory.**.** ^Th
36eb0 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  e sqlite3_releas
36ec0 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72  e_memory() inter
36ed0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
36ee0 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a   free N bytes.**
36ef0 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
36f00 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20  by deallocating 
36f10 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
36f20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
36f30 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20  .** held by the 
36f40 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79  database library
36f50 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20  .   Memory used 
36f60 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73  to cache databas
36f70 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d  e.** pages to im
36f80 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
36f90 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  e is an example 
36fa0 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  of non-essential
36fb0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c   memory..** ^sql
36fc0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
36fd0 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68  ory() returns th
36fe0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
36ff0 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64  s actually freed
37000 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74  ,.** which might
37010 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73   be more or less
37020 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74   than the amount
37030 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e   requested..** ^
37040 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  The sqlite3_rele
37050 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75  ase_memory() rou
37060 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20  tine is a no-op 
37070 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a  returning zero.*
37080 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 6e  * if SQLite is n
37090 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ot compiled with
370a0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
370b0 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
370c0 54 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  T]..*/.SQLITE_AP
370d0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  I int sqlite3_re
370e0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74  lease_memory(int
370f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37100 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d  EF: Impose A Lim
37110 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a  it On Heap Size.
37120 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37130 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
37140 69 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  it64() interface
37150 20 73 65 74 73 20 61 6e 64 2f 6f 72 20 71 75 65   sets and/or que
37160 72 69 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66 74  ries the.** soft
37170 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d   limit on the am
37180 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d  ount of heap mem
37190 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20  ory that may be 
371a0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
371b0 69 74 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ite..** ^SQLite 
371c0 73 74 72 69 76 65 73 20 74 6f 20 6b 65 65 70 20  strives to keep 
371d0 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 74 69 6c  heap memory util
371e0 69 7a 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74 68  ization below th
371f0 65 20 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20 6c  e soft heap.** l
37200 69 6d 69 74 20 62 79 20 72 65 64 75 63 69 6e 67  imit by reducing
37210 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
37220 61 67 65 73 20 68 65 6c 64 20 69 6e 20 74 68 65  ages held in the
37230 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61   page cache.** a
37240 73 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73  s heap memory us
37250 61 67 65 73 20 61 70 70 72 6f 61 63 68 65 73 20  ages approaches 
37260 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  the limit..** ^T
37270 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
37280 69 74 20 69 73 20 22 73 6f 66 74 22 20 62 65 63  it is "soft" bec
37290 61 75 73 65 20 65 76 65 6e 20 74 68 6f 75 67 68  ause even though
372a0 20 53 51 4c 69 74 65 20 73 74 72 69 76 65 73 20   SQLite strives 
372b0 74 6f 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f 77  to stay.** below
372c0 20 74 68 65 20 6c 69 6d 69 74 2c 20 69 74 20 77   the limit, it w
372d0 69 6c 6c 20 65 78 63 65 65 64 20 74 68 65 20 6c  ill exceed the l
372e0 69 6d 69 74 20 72 61 74 68 65 72 20 74 68 61 6e  imit rather than
372f0 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e 20   generate.** an 
37300 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65  [SQLITE_NOMEM] e
37310 72 72 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72 20  rror.  In other 
37320 77 6f 72 64 73 2c 20 74 68 65 20 73 6f 66 74 20  words, the soft 
37330 68 65 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20 69  heap limit .** i
37340 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e  s advisory only.
37350 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
37360 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
37370 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
37380 6c 69 6d 69 74 36 34 28 29 20 69 73 20 74 68 65  limit64() is the
37390 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20   size of.** the 
373a0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
373b0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c  prior to the cal
373c0 6c 2e 20 20 5e 49 66 20 74 68 65 20 61 72 67 75  l.  ^If the argu
373d0 6d 65 6e 74 20 4e 20 69 73 20 6e 65 67 61 74 69  ment N is negati
373e0 76 65 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63 68  ve.** then no ch
373f0 61 6e 67 65 20 69 73 20 6d 61 64 65 20 74 6f 20  ange is made to 
37400 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
37410 6d 69 74 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  mit.  Hence, the
37420 20 63 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a 65   current.** size
37430 20 6f 66 20 74 68 65 20 73 6f 66 74 20 68 65 61   of the soft hea
37440 70 20 6c 69 6d 69 74 20 63 61 6e 20 62 65 20 64  p limit can be d
37450 65 74 65 72 6d 69 6e 65 64 20 62 79 20 69 6e 76  etermined by inv
37460 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
37470 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
37480 36 34 28 29 20 77 69 74 68 20 61 20 6e 65 67 61  64() with a nega
37490 74 69 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tive argument..*
374a0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67  *.** ^If the arg
374b0 75 6d 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f 20  ument N is zero 
374c0 74 68 65 6e 20 74 68 65 20 73 6f 66 74 20 68 65  then the soft he
374d0 61 70 20 6c 69 6d 69 74 20 69 73 20 64 69 73 61  ap limit is disa
374e0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  bled..**.** ^(Th
374f0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
37500 74 20 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65  t is not enforce
37510 64 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  d in the current
37520 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
37530 2a 2a 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  ** if one or mor
37540 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 63  e of following c
37550 6f 6e 64 69 74 69 6f 6e 73 20 61 72 65 20 74 72  onditions are tr
37560 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ue:.**.** <ul>.*
37570 2a 20 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74 20  * <li> The soft 
37580 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 73 65  heap limit is se
37590 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c  t to zero..** <l
375a0 69 3e 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75 6e  i> Memory accoun
375b0 74 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64  ting is disabled
375c0 20 75 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e 61   using a combina
375d0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20  tion of the.**  
375e0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e      [sqlite3_con
375f0 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
37600 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 2e  FIG_MEMSTATUS],.
37610 2e 2e 29 20 73 74 61 72 74 2d 74 69 6d 65 20 6f  ..) start-time o
37620 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20  ption and.**    
37630 20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45    the [SQLITE_DE
37640 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d  FAULT_MEMSTATUS]
37650 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
37660 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e  tion..** <li> An
37670 20 61 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67   alternative pag
37680 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
37690 74 61 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66  tation is specif
376a0 69 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ied using.**    
376b0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69    [sqlite3_confi
376c0 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
376d0 47 5f 50 43 41 43 48 45 5d 2c 2e 2e 2e 29 2e 0a  G_PCACHE],...)..
376e0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61 67 65  ** <li> The page
376f0 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 73   cache allocates
37700 20 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65   from its own me
37710 6d 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69  mory pool suppli
37720 65 64 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b 73  ed.**      by [s
37730 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
37740 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
37750 47 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61  GECACHE],...) ra
37760 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
37770 20 20 66 72 6f 6d 20 74 68 65 20 68 65 61 70 2e    from the heap.
37780 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
37790 2a 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68  * Beginning with
377a0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
377b0 33 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66 74 20  3.7.3, the soft 
377c0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e  heap limit is en
377d0 66 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61 72 64  forced.** regard
377e0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
377f0 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
37800 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
37810 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20  _MANAGEMENT].** 
37820 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
37830 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
37840 20 57 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e   With [SQLITE_EN
37850 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
37860 47 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20  GEMENT],.** the 
37870 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
37880 69 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e 20 65  is enforced on e
37890 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
378a0 63 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f 75 74  cation.  Without
378b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
378c0 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
378d0 4d 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66 74 20  MENT], the soft 
378e0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6f 6e  heap limit is on
378f0 6c 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 77  ly enforced.** w
37900 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c  hen memory is al
37910 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 70  located by the p
37920 61 67 65 20 63 61 63 68 65 2e 20 20 54 65 73 74  age cache.  Test
37930 69 6e 67 20 73 75 67 67 65 73 74 73 20 74 68 61  ing suggests tha
37940 74 20 62 65 63 61 75 73 65 0a 2a 2a 20 74 68 65  t because.** the
37950 20 70 61 67 65 20 63 61 63 68 65 20 69 73 20 74   page cache is t
37960 68 65 20 70 72 65 64 6f 6d 69 6e 61 74 65 20 6d  he predominate m
37970 65 6d 6f 72 79 20 75 73 65 72 20 69 6e 20 53 51  emory user in SQ
37980 4c 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70  Lite, most.** ap
37990 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  plications will 
379a0 61 63 68 69 65 76 65 20 61 64 65 71 75 61 74 65  achieve adequate
379b0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
379c0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77 69 74   enforcement wit
379d0 68 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73 65 20  hout.** the use 
379e0 6f 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  of [SQLITE_ENABL
379f0 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
37a00 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ENT]..**.** The 
37a10 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 75 6e  circumstances un
37a20 64 65 72 20 77 68 69 63 68 20 53 51 4c 69 74 65  der which SQLite
37a30 20 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20 74 68   will enforce th
37a40 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
37a50 74 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67 65 73  t may.** changes
37a60 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
37a70 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
37a80 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
37a90 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
37aa0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
37ab0 69 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74  it64(sqlite3_int
37ac0 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  64 N);../*.** CA
37ad0 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
37ae0 65 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d  ed Soft Heap Lim
37af0 69 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20  it Interface.** 
37b00 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
37b10 20 54 68 69 73 20 69 73 20 61 20 64 65 70 72 65   This is a depre
37b20 63 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  cated version of
37b30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f   the [sqlite3_so
37b40 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
37b50 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
37b60 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69    This routine i
37b70 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68  s provided for h
37b80 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
37b90 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e  ibility.** only.
37ba0 20 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63    All new applic
37bb0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73  ations should us
37bc0 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
37bd0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
37be0 74 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65  t64()] interface
37bf0 20 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 69   rather than thi
37c00 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  s one..*/.SQLITE
37c10 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
37c20 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
37c30 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
37c40 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a  mit(int N);.../*
37c50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
37c60 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41  tract Metadata A
37c70 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66  bout A Column Of
37c80 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e   A Table.**.** ^
37c90 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
37ca0 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62  urns metadata ab
37cb0 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63  out a specific c
37cc0 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69  olumn of a speci
37cd0 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  fic.** database 
37ce0 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65  table accessible
37cf0 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61   using the [data
37d00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37d10 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65   handle.** passe
37d20 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66  d as the first f
37d30 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
37d40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
37d50 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65  umn is identifie
37d60 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c  d by the second,
37d70 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
37d80 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a  h parameters to.
37d90 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
37da0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
37db0 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65  rameter is eithe
37dc0 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  r the name of th
37dd0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69  e database.** (i
37de0 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d  .e. "main", "tem
37df0 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63 68  p", or an attach
37e00 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e  ed database) con
37e10 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63  taining the spec
37e20 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f  ified.** table o
37e30 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69  r NULL. ^If it i
37e40 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c  s NULL, then all
37e50 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
37e60 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64  ses are searched
37e70 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c  .** for the tabl
37e80 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
37e90 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20   algorithm used 
37ea0 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
37eb0 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73  engine to.** res
37ec0 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64  olve unqualified
37ed0 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65   table reference
37ee0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  s..**.** ^The th
37ef0 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
37f00 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
37f10 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74  s function are t
37f20 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  he table and col
37f30 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  umn.** name of t
37f40 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
37f50 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
37f60 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
37f70 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  e parameters.** 
37f80 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  may be NULL..**.
37f90 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73 20  ** ^Metadata is 
37fa0 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74  returned by writ
37fb0 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ing to the memor
37fc0 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73  y locations pass
37fd0 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a  ed as the 5th.**
37fe0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
37ff0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
38000 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e  is function. ^An
38010 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d  y of these argum
38020 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e  ents may be.** N
38030 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ULL, in which ca
38040 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  se the correspon
38050 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20  ding element of 
38060 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74  metadata is omit
38070 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c  ted..**.** ^(<bl
38080 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
38090 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
380a0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61  ** <tr><th> Para
380b0 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75  meter <th> Outpu
380c0 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  t<br>Type <th>  
380d0 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a  Description.**.*
380e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c  * <tr><td> 5th <
380f0 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
38100 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a  <td> Data type.*
38110 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c  * <tr><td> 6th <
38120 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
38130 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66  <td> Name of def
38140 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ault collation s
38150 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c  equence.** <tr><
38160 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74  td> 7th <td> int
38170 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
38180 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73  ue if column has
38190 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73   a NOT NULL cons
381a0 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74  traint.** <tr><t
381b0 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 8th <td> int 
381c0 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
381d0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70  e if column is p
381e0 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41  art of the PRIMA
381f0 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74  RY KEY.** <tr><t
38200 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 9th <td> int 
38210 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
38220 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b  e if column is [
38230 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a  AUTOINCREMENT].*
38240 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
38250 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
38260 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
38270 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
38280 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e  e character poin
38290 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f  ters returned fo
382a0 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61  r the.** declara
382b0 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f  tion type and co
382c0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
382d0 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75   is valid only u
382e0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a  ntil the next.**
382f0 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c   call to any SQL
38300 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e  ite API function
38310 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
38320 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20  specified table 
38330 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69  is actually a vi
38340 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ew, an [error co
38350 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
38360 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  .**.** ^If the s
38370 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20  pecified column 
38380 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64  is "rowid", "oid
38390 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61  " or "_rowid_" a
383a0 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45  nd an.** [INTEGE
383b0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63  R PRIMARY KEY] c
383c0 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65  olumn has been e
383d0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
383e0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  ed, then the out
383f0 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
38400 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68  s are set for th
38410 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  e explicitly dec
38420 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28  lared column. ^(
38430 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a  If there is no.*
38440 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  * explicitly dec
38450 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50  lared [INTEGER P
38460 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75  RIMARY KEY] colu
38470 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  mn, then the out
38480 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
38490 73 20 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c  s are set as fol
384a0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  lows:.**.** <pre
384b0 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79  >.**     data ty
384c0 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a  pe: "INTEGER".**
384d0 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73       collation s
384e0 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59  equence: "BINARY
384f0 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c  ".**     not nul
38500 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d  l: 0.**     prim
38510 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20  ary key: 1.**   
38520 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74    auto increment
38530 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a  : 0.** </pre>)^.
38540 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e  **.** ^(This fun
38550 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f  ction may load o
38560 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d  ne or more schem
38570 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  as from database
38580 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a   files. If an.**
38590 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
385a0 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73  ring this proces
385b0 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71  s, or if the req
385c0 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20  uested table or 
385d0 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74  column.** cannot
385e0 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65   be found, an [e
385f0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
38600 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72  turned and an er
38610 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74  ror message left
38620 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61  .** in the [data
38630 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38640 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65   (to be retrieve
38650 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
38660 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a  errmsg()).)^.**.
38670 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73 20  ** ^This API is 
38680 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
38690 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
386a0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
386b0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
386c0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
386d0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
386e0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
386f0 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ined..*/.SQLITE_
38700 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
38710 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74  table_column_met
38720 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33  adata(.  sqlite3
38730 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
38740 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69       /* Connecti
38750 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  on handle */.  c
38760 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
38770 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61  me,        /* Da
38780 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e  tabase name or N
38790 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ULL */.  const c
387a0 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c  har *zTableName,
387b0 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61       /* Table na
387c0 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  me */.  const ch
387d0 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c  ar *zColumnName,
387e0 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61      /* Column na
387f0 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  me */.  char con
38800 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c  st **pzDataType,
38810 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44      /* OUTPUT: D
38820 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79